CP/M/CPM_CDROM.iso/cpm/utils/dirutl/chdir.lbr/CHDIR.HZP/CHDIR.HLP

Text File | 1987-12-26 | 29KB | 662 lines

Overview of CHDIR
Installation
Basic Definitions
Moving Into a Directory
Creation of New Directories "On the Fly"
Displaying the Directories
Setup Mode
Planning a Directory Structure
:Overview of CHDIR

     CHDIR  (CHange DIRectory) is a program which gives a CP/M or
CP/ZM system a new virtual directory structure.   Ever since CP/M
2.0 came out, users have been forced to refer to the environments
that  their  files are located in by user number and  disk  name.
This was an improvement over CP/M 1.4 in that projects and  files
associated  to  each  other for one reason or  another  could  be
logically  grouped together into a user area on a particular disk
and could easily be kept separate from other files.

     This improvement is desirable and useful, but there are some
capabilities  lacking in this design that limit  its  usefulness.
One  such capability is the need for duplication of a COM file or
directory entry for a COM file in order to access this file  from
more  than one user area.   Another such capability is the human-
interface  requirement  for  a  logically-named  user  area  that
indicates  the  purpose  of the user area as  opposed  to  simply
providing a number for it.

     Under  CP/M  2.x,  unfortunately,  if you wanted to issue  a
command,  you  had to have a copy of that particular COM file  in
your current user area in order for the operating system to  find
the command and load it.   User areas were of less use because of
this,  since  several commonly-used commands had to be duplicated
into  each  user  area.   This took up more disk  space  and  was
somewhat awkward.

     In answer to this and other desired capabilities,  ZCPR  was
created.   Placed  on  top of the CP/M CCP,  ZCPR provides a  new
command  processor for the CP/M user which is  upward  compatible
with  the  old command processor but adds several  new  features,
including a command-search hierarchy.   Now, when a user issues a
command,  ZCPR  will  search  for it if it is not  found  in  the
current user area on the current or specified disk.  The user can
specify the path to follow; however, ZCPR is initially configured
to search the current user area on the current disk,  user area 0
on  the current disk,  and user area 0 of disk A before producing
an  error message.   With ZCPR it is no longer necessary to  keep
several copies of files on disk in order to use the user areas.

     The  user areas and disks were still addressed  as  separate
elements of an overall file system,  however.  The user had to be
constantly  aware  of  where he was,  and ZCPR also  gave  him  a
different  prompt  which  indicated  the current  disk  and  user
number.   If  a user wished to employ user area 1 for  C  program
development and user area 2 for C source code storage,  he had to
note for himself that this is where these things were.

     Now,  CHDIR  is  introduced which adds a new outlook to  the
user  environment.   The user may now give each user area/disk  a
logical name (such as C-DEV or C-PGMS) and not worry about  where
they  actually are on disk.   Combined wisely with ZCPR or ZMCPR,
all utilities may be placed in a commonly-scanned directory (user
area/disk)  so  they will always be found by  the  CPR,  and  the
user's  entire microcomputer disk system now resembles one  large
disk  with  several  named subdirectories which  contain  related
files.

     CHDIR artificially imposes a named directory structure  onto
CP/M and CP/ZM.   Each named directory corresponds to a user area
on  a particular disk,  and the user need never be concerned with
what  user  area he is in if he uses ZCPR or  ZMCPR  with  CHDIR.
Each  disk/user  area  is called a directory and may be  given  a
logical name (up to 8 characters long).

     The simplest form of the CHDIR command is:

          CHDIR <directory name>

where <directory name> is a logical name (8 chars max) recognized
by  CHDIR.   This command logs the user into the  user  area/disk
associated with the indicated directory name.

     For example, given the following environment:

          User Disk Directory
           10    A  SYS1
           11    A  SYS2
            8    B  C-DEV
            7    A  C-PGMS
            7    B  PAS-DEV
            6    A  PAS-PGMS

the command:

          CHDIR C-DEV

logs the user into user area 8 on Drive B:; also, the command:

          CHDIR PAS-PGMS

logs the user into user area 6 on Drive A:.
     CHDIR combined with ZCPR or ZMCPR,  then,  provides a useful
named-directory  working environment which is completely  compat-
ible  with  CP/M,  and almost all CP/M programs can  run  without
modification in this new environment.

     CHDIR  employed  in a hard disk  environment  is  especially
useful  in  that the different logical disks associated with  the
hard  disk may now be grouped into one named directory  structure
and need no longer be treated as separate disks.

     In  addition  to the named directory structure,  CHDIR  also
creates a priveleged user environment.   This environment,  which
only  becomes  effective  if the USER  command  (and  other  such
facilities) are removed from ZCPR (and the COM files removed from
the disk),  defines two classes of users.  A normal user only has
access  to  certain  user  areas  (0 to  9  by  default),  and  a
priveleged user has access to all user areas.   In order to  move
into user areas greater than 9,  a password must be known.   Once
in  a priveleged user area,  no password is necessary to move  to
any other user area.

     This  feature  gives  a  certain  amount  of  protection  to
systems,  such as Remote Bulletin Board Systems,  against hostile
users.   Certain  priveleged  commands,  such  as  debuggers  and
language utilities,  may be placed into the protected user  areas
and employed only by those who know the password.   Two different
command  processors  can even be made to come into play  (in  the
case  of ZMCPR),  where the normal user sees a menu-driven set of
commands while a priveleged user sees a ZCPR-like command line.

     Refer  to  the documentation on ZCPR and ZMCPR  for  further
details.

:Installation
     Installation of CHDIR is performed in two parts:   Compiling
CHDIR and Initializing the Internal Buffers of CHDIR.


     Before  compiling CHDIR,  there are several internal default
values  that the user may wish to set in the source code  of  the
program.  These values and their meanings are:

          defname  -- default  name  for the COM file  of  CHDIR;
change  this  if you want CHDIR to be known by  some  other  name
after  initialization;  this name may also be later changed under
Setup Mode
          dirmax -- maximum number of directory names allowed;  a
minimum value of 64 is recommended
          syspass -- default System Password for CHDIR;  this  is
up  to 20 characters long,  and case is significant;  this may be
later changed under the Setup Mode

          sysuser  -- lowest user number for a  priveleged  user;
default value is 10; values should be in the range from 0 to 15
          tryent   -- number  of  tries  permitted  to  enter   a
priveleged directory before CHDIR aborts; default value is 1
          tryset -- number of tries permitted to enter Setup Mode
before CHDIR aborts; default value is 3
          exitcmd  -- command to be executed if a valid  password
is  not  given  in the required number of tries;  default  is  no
command;  this should be the name of a COM file,  like  "HOSTILE"
for HOSTILE.COM, and should be in upper-case

     All  of  these  defined values are located  just  after  the
initial comments within the program source code.


                    Part I -- Compiling CHDIR

     CHDIR was compiled by the BDS C compiler.   No special flags
or options are necessary.   Once compiled,  however, the COM file
produced  must be modified so that the stack used by this program
does not overwrite the CCP or CPR.

     To do this, the user may use the NOBOOT program from the BDS
C  user's group or manually modify the code at the  beginning  of
the  COM file.   Using the 1.45 version of BDS C,  the first  few
bytes  of the COM file load the HL register pair from locations 6
and 7 and then load the SP register from HL.  This is followed by
several  NOPs.   To  correct  the  stack  problem,  replace  this
sequence with an LXI D,-A00H,  DAD D,  and SPHL starting with the
SPHL instruction.  Example follows:

     Original Code       New Code

     LHLD 6              LHLD 6
     SPHL                LXI D,-A00H
     NOP
     NOP
     NOP                 DAD D
     NOP                 SPHL

     Once this has been installed using a debugger like DDT,  the
COM file may be resaved to disk using the SAVE command,  and  the
user is ready to proceed to Part II of the installation.   If the
NOBOOT  command is available and works for the user's version  of
BDS C, then this manual procedure may be replaced by the command:

          NOBOOT CHDIR.COM


              Part II -- Initializing CHDIR Buffers

     Once  CHDIR.COM has been patched so that it's stack does not
overwrite  the  CCP or CPR,  then its internal  buffers  must  be
initialized.  This is done to perform two basic functions:

          1) define the password for the priveleged user
          2) clear the directory name table

     To perform this initialization, issue the command:

          CHDIR /S

     This places the user into SETUP Mode.  If the user runs this
command from user areas 0 to 9,  he will be asked for the "System
Password",  which is initially "chdir" (no quotes).   If the user
runs this command from user areas greater than 9,  he is declared
priveleged and is not asked for the password.
     Once into SETUP Mode, the user is prompted with:

          Setup Command (? for Help)?

     He  should  issue  the  following commands  to  perform  the
initialization:

          I or i -- clear the directory name table; the user will
be  prompted  with "Verify Initialization (Y/N)?",  to  which  he
should respond with a Y or y.

          P or p -- set the password;  the user will be  prompted
with  "New System Password?" and 20 dots to indicate the size  of
the  allotted password;  he may then type the new  password,  and
case is significant ("test" is NOT the same as "TEST")

          X or x -- Exit and rewrite CHDIR.COM to disk;  the user
will be prompted with "Write New File (Y/N)?", to which he should
respond with Y or y, and then "Name of File (RETURN=CHDIR.COM)?",
to which he should strike the RETURN key.

     SETUP  Mode  is described in more detail later in  this  HLP
file.   The  procedure just outlined is all that is required  for
initialization, and CHDIR is now ready for use.

     The  first step is to plan and define the named directories.
The other sections of this HLP file tell you how to do this.
:Basic Definitions
     The following symbolic names are defined:

          <directory name>    <du>      <password>

     A  <directory  name> may contain up to  8  characters.   The
characters "*",  "?",  ".", and "/" should not be used as part of
the directory name since the CCP,  CPR, or CHDIR routines perform
special processing on them.  Lower-case letters are automatically
converted to upper-case.

     <du> is the disk letter and user number combination which is
assigned  to the <directory name> given.   It is a single  letter
(lower-case  is converted to upper-case) in the range from A to P
followed immediately by the digits of the user number (0 to 15).

     <password>  is  the System Password for CHDIR.   This  is  a
string  of up to 20 characters.   Case is significant ("test"  is
NOT the same as "TEST"),  and any printable character may be used
as part of the password as a general rule.

:Moving Into a Directory
     The CHDIR command of the following form is used to move into
a directory:

          CHDIR <directory name>

     A  <directory  name> may contain up to  8  characters.   The
characters "*",  "?",  ".", and "/" should not be used as part of
the directory name since the CCP,  CPR, or CHDIR routines perform
special processing on them.  Lower-case letters are automatically
converted to upper-case.

     If  the user is not priveleged (residing in user area 10  or
greater,  by  default) and the name of a priveleged directory  is
given,  he will be asked for the System Password.   In this case,
he will be given only one try before the command aborts.

     Examples:
          CHDIR C-DEV              CHDIR work
          chdir cpci81             chdir 1temp
:Creation of New Directories "On the Fly"
     The  CHDIR command of the following form is used  to  create
new directories at will:

          CHDIR <directory name> <du>

     <directory name> is of the same form as described above.

     <du> is the disk letter and user number combination which is
assigned  to the <directory name> given.   It is a single  letter
(lower-case is converted to upper-case) in the range from A to  P
followed immediately by the digits of the user number (0 to 15).

     If  the user issues this command and is not priveleged (run-
ning from user area 10 or greater,  by default),  then he will be
asked for the System Password before the command is executed.  If
he is priveleged, CHDIR will execute the command without prompt.

     Examples:
          CHDIR C-DEV A5                chdir 1temp m0
          chdir work b4                 chdir sys1 a10
:Displaying the Directories
     The  CHDIR command of the following form is used to  display
the names of the existing directories:

          CHDIR /DISPLAY

     Only  the  "/D"  is required to complete  the  command;  any
characters following the "/D" are ignored.

     If  the  user is not  priveleged,  only  the  non-priveleged
directories are displayed.   If he is priveleged, all directories
are  displayed.   A  priveleged  user is identified by  the  user
number  he is currently residing in (10 and above are  priveleged
by default).

     A count of the number of directory names defined and  amount
of directory space left for more names is given, and, if the user
is  not priveleged,  the count of defined names may not match the
number of displayed directory names since he is not permitted  to
see the names of the priveleged directories.

:Setup Mode
     The CHDIR command of the following form places the user into
Setup Mode:

          CHDIR /SETUP

     Only  the  "/S"  is required to complete  the  command;  any
characters following the "/S" are ignored.

     Setup Mode is employed by a priveleged user to:
          1) initialize the directory names
          2) set/change the System Password
          3) add/delete directory names
          4) display the System Password and directory names
          5) sort the directory names by disk/user area
          6) save the current named directory structure to disk

     If  the  "CHDIR  /SETUP"  command  is  issued  from  a  non-
priveleged  user  area (user areas 0 to 9 by default),  then  the
user  will be prompted for the System Password.   He is  given  3
tries to get it right before CHDIR aborts (by default).

     Once in Setup Mode, the user is prompted with

          Setup Command (? for Help)?

and  Setup  is  waiting for the user to type  a  single-character
command  letter.   If he types a ?  or any other invalid  command
letter,  he  is presented with a summary of the Setup  Mode  com-
mands.   These  commands are invoked by striking a single  letter
and case is not significant.  A summary of these commands is:

          D -- Display System Password and Directory Names
          I -- Initialize and Clear All Directory Names
          N -- Create a New Directory Name
          P -- Set the System Password
          Q -- Quit without Updating
          S -- Sort Directory by Disk and User Number
          X -- Exit and Update CHDIR.COM on Disk

     Each command is explained on the following screens.
        D -- Display System Password and Directory Names

     This command prints three groups of information.  They are:

        "System  Password  is ..."
               -- current setting for the System Password
        "Defined Directory Names --
             du: name1      du: name2      du:name3     du:name4"
               -- disk, user area, and name for directories
                    4 entries are printed per line
        "n Directory Names Defined, Space Left for m More Names"
               -- number of names defined and space left
          I -- Initialize and Clear All Directory Names

     This command performs the following initializations:

          1)  the  System  Password  is renamed  to  the  default
programmed value of the variable syspass;  this name is initially
"chdir"
          2)  all  disk names,  user areas,  and  directory  name
strings are initialized to zero

     The  user  is prompted with "Verify  Initialization  (Y/N)?"
immediately  after he strikes the letter I or i.   If  he  replys
with  any letter other than Y or y,  the message  "Initialization
Aborted"  is  printed and he is returned to Setup Command  level.
If  he  types  a  Y  or  y  in  response  to  this  prompt,   the
initialization is performed and the message "All Directory  Names
Cleared" is printed.
                N -- Create a New Directory Name

     In response to this command, the message

          "System User Areas start at nn"

is  printed  to remind the user where the priveleged  user  areas
begin, and the user is placed into a loop, prompted with

          "Disk Letter and User (RETURN=Done or A-P 0-15)?"

     If  the user wishes to create a new directory,  he types one
letter A-P (case is not significant) followed by a number in  the
range  from 0 to 15.   If the user does not wish to create a  new
directory,  he  strikes the RETURN key to abort to Setup  Command
level.

           N -- Create a New Directory Name, Continued

     If  the user selected a valid disk/user combination,  he  is
prompted with

          "Directory Name (RETURN = Delete Old Name)?"

to  which  he may strike the RETURN key to delete  the  directory
name previously associated with the disk/user specified or he may
type a directory name (case is not significant and all lower-case
letters  are capitalized) to create a new directory or rename  an
old one.

     If  the  directory  name or RETURN is  accepted,  the  "Disk
Letter  and  User"  prompt will reappear to  allow  the  user  to
continue  creating  directory  names or abort  to  Setup  Command
level.
           N -- Create a New Directory Name, Continued

     Several  error  messages are possible while in this part  of
the Setup Mode.  These messages are:

     "Invalid Disk Letter"
          -- Disk was not in the range from A to P
     "Invalid User Number"
          -- User Number was not in the range from 0 to 15
     "Directory Name is too long -- Reenter"
          -- Entered directory name exceeded 8 characters
     "Error -- Directory Name Buffer Full"
          -- No more space is available in the internal buffer
     "Directory Name for ud: Deleted"
          -- (NOT an error message) Tells the user that a
               previously-defined name was deleted
                  P -- Set the System Password

     This  command in Setup Mode is immediately followed  by  the
prompt

          "New System Password?"

to which the user is allowed to enter up to 20 characters for his
password.  The user MUST enter a password; simply typing a RETURN
sets the password to null and a simple RETURN is required for the
new password when asked.
                   Q -- Quit without Updating

     This command is answered with the prompt

          "Verify Abort (Y/N)?"

to  which  the  user replys with Y or y to abort Setup  Mode  and
return  to the operating system or any other character to  return
to Setup Mode.
           S -- Sort Directory by Disk and User Number

     This  command causes the internal directory to be sorted  by
disk and user area.  In response to this command, CHDIR sorts the
directory (no informative prompt) and prints

          "Sort Complete"

when done.

     This command is provided for the convenience of the user.
             X -- Exit and Update CHDIR.COM on Disk

     This command causes the prompt

          "Write New File (Y/N)?"

to appear.  If the user responds with anything other than Y or y,
Setup  Mode and CHDIR are aborted and control is returned to  the
operating system.

     If the user responds with Y or y, he is prompted with

          "Name of File (RETURN = CHDIR.COM)?"

to  which he may reply by striking the RETURN key to rewrite  the
file CHDIR.COM on disk or he may give another file name (the .COM
is  not necessary) to write a new file.   The  current  directory
structure  is  defined as a part of the written file,  and it  is
used  to  access  this new  directory  ala  CHDIR  commands.   In
entering the file name, case is not significant.
        X -- Exit and Update CHDIR.COM on Disk, Continued

     The  prompt  may  vary if CHDIR has been rewritten  under  a
different name.  By default, the prompt is

          "Name of File (RETURN = CHDIR.COM)?"

and,  if,  for  instance,  CHDIR was rewritten as  CDIR.COM,  the
prompt from CDIR would be

          "Name of File (RETURN = CDIR.COM)?"

     Once  the  file name is specified or RETURN is  struck,  the
following messages appear:

          "Sorting Directory by Disk and User Number"
          "Writing File CHDIR.COM to Disk ..."
               " File CHDIR.COM Written to Disk"

     An  error message "Error -- Can't Create File CHDIR.COM"  is
possible, indicating that the disk or directory are full.
                    Other Setup Mode Commands

     Striking  any key other than those just described  causes  a
built-in Help message to be displayed.   Control is then returned
to Setup Mode command level.
:Planning a Directory Structure

     This section outlines a few comments and recommendations  on
a  technique  to  combine ZCPR or ZMCPR with CHDIR  to  create  a
working environment.

     The ZCPR and ZMCPR command-search hierarchy frequently  take
the  user  down to user 0 on drive A before the  invalid  command
error message is given.  This directory is, effectively, the ROOT
of  the  system,  and  this would be a good place  to  store  the
CHDIR.COM  file.   "ROOT"  itself is a good name for A0,  and  by
standardizing on this name, any user can place himself here as he
moves between systems and see the standard command set.

     Since  a  command-search  hierarchy is used under  ZCPR  and
ZMCPR,  this,  in conjunction with CHDIR, can be used to create a
hierarchial  directory structure.   The first CHDIR.COM  that  is
encountered  during a search is the one that is effective,  so by
placing a CHDIR.COM in the command-search path before the ROOT is
encountered, directory subtrees can be formed.  Let me illustrate
this concept with the following diagram:
              CHDIR Directories                   Tree

Disk A:   User 0: CHDIR.COM                    (1)ROOT --> WORK
Directories:   A0: ROOT       B0: WORK

Disk B:   User 0: CHDIR.COM
Directories:   A0: ROOT                                    ROOT
               B0: C-ROOT     B1: C-DEV                    C-DEV
               B2: C-PGMS     B3: C-DOC      (2)C-ROOT --> C-PGMS
          User 1: No CHDIR.COM                             C-DOC
          User 2: No CHDIR.COM
          User 3: CHDIR.COM
Directories:   B0: C-ROOT     B3: C-DOC
               B4: COMPILER   B5: PROGRAM                  C-ROOT
          User 4: No CHDIR.COM                (3)C-DOC --> COMPILER
          User 5: No CHDIR.COM                             PROGRAM
     Using  the normal ZCPR command-search  hierarchy,  which  is
current  user/current disk to user 0/current disk to user  0/disk
A, the following can be noted:

          A) tree (1) is seen from any user number on A:
          B) tree (2) is seen from any user number except 3 on B:
          C) tree (3) is seen from user 3 on B:

     As  the  reader can see,  this is a very  powerful  concept.
Let's  say  that  you  are logged into A0 and want  to  read  the
documentation on the C compiler.   You would have to issue "CHDIR
WORK" to enter the directory WORK on B:.  Issuing "CHDIR /D" from
here shows you in directory C-ROOT,  and you now issue "CHDIR  C-
DOC"  to enter the documentation branch of the tree.   From here,
you  issue "CHDIR COMPILER" to enter the  compiler  documentation
directory.  Expressed as a tree, this is:

     Feel  free  to move back to the previous displays via the  L
command if this is not clear to you.

                              ROOT
                                !
                          C-ROOT (WORK)
                         /      !      \
                      C-DEV   C-PGMS  C-DOC
                                      /  \
                               COMPILER  PROGRAMS

     This  is  a  simple type of tree  structure  as  implemented
above.  CHDIR goes beyond this, tho, and allows as much as a star
or ring structure as well, or any combination desired.

     One  more  step that CHDIR allows the user to take  is  with
priveleged  users.   Now,  directories can be hidden from  normal
users.   Priveleged  directories are set up like normal director-
ies,  and CHDIR is the program which enforces the security.  Note
that  the USER command must be removed from the CPR for  this  to
work.

     Using  ZMCPR adds a capability of logging into a new direct-
ory  and automatically invoking a new command  interpreter.   The
MENU.CCP  file  can  be either a menu display  or  an  executable
program,  and  as  an executable program,  it is run  every  time
control is returned to the CPR while the user is logged into  the
current  directory.   In this way,  a whole new command processor
can be introduced with each directory, and as the user moves from
one directory to another,  he may move from menu-driven  displays
to ZCPR-like command line processors to other processors at will.
The capabilities and potential are amazing!


     Yet  another change may be made to enhance the  capabilities
of  CHDIR.   This  change involves modifying  the  command-search
hierarchy to a new path.  For example:

          Old Path: User Current/Disk Current
                    User 0/Disk Current
                    User 0/Disk A

          New Path: User Current/Disk Current
                    User Current/Disk A
                    User 0/Disk A

     This provides a new CHDIR environment in which utilities can
be  grouped into different directories on A and all the work done
on B.   When a command is issued,  command search falls to a pro-
ject utility area on A before falling to the ROOT.  The differen-
ces between these to paths can be illustrated as follows:

          Old Path: User Current/Disk Current
                    User 0/Disk Current
                    User 0/Disk A

          New Path: User Current/Disk Current
                    User Current/Disk A
                    User 0/Disk A

------
          Old Path: Work Area --> Common Root Utilities --> ROOT
          New Path: Work Area --> Project Utilities --> ROOT

     Under  the new path,  different user areas on A can  contain
the utilties, say, associated with a particular language, such as
user 1 for C,  user 2 for PASCAL,  etc.   Then, the corresponding
work  areas on B would be user 1 for C work,  user 2  for  PASCAL
work,  etc.   Now, when a command is issued, the move from C work
to C compiler to ROOT or PASCAL work to PASCAL compiler to ROOT.

     As  the  reader can see,  the possibilities are  staggering.
And this is just the beginning.

     I hope you enjoy using CHDIR with ZCPR and ZMCPR,  and don't
hesitate to experiment with the possibilities available by  these
combinations.   Comments  on these programs and any new ideas the
reader has would be appreciated.

                                        Richard Conn