ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/CPM/ZCPR33/A-R/EDITND.LBR/EDITND.DZC/EDITND.DOC

Text File | 2000-06-30 | 22KB | 514 lines

Program: EDITND   - EDIT the resident Named Directory
Author: Al Hawley, Ladera Z-Node, [phone]

EDITND is copyright by A. E. Hawley January 30, 1987.
It may be freely distributed, but it must not be sold
either separately or as part of a package without the
written consent of the author.  The author may be reached
via electronic mail at the Ladera Z-Node in Los Angeles,
213-670-9465, or through the Lillipute Z-Node in Chicago
at 312-649-1730.

EDITND is released for beta test through the Z-system
users group Z-SIG on January 30, 1987 by the author.

PROGRAM FUNCTION:
     Edit  the System Named Directory.  Change,  add,  or  delete ì
directory  names and passwords.  The changes are to the  resident ì
Named Directory buffer, and may be aborted (restored to original) ì
if desired.
     Why would you want to mess with the system NDR? Read on...


     ZCPR3  as originally released included an impressive set  of ì
utilities  (now called ZTOOLS).  These utilities create,  modify, ì
and  make use of the ZCPR3 environment to provide the  user  with ì
facilities  like  those  of many mini- and  main-frame  operating ì
systems.  Named  Directories are used by many of the  tools,  and ì
recognized as arguments by all. The manipulation of the currently ì
resident Named DiRectory is the subject of this documentation and ì
of two programs not in the original set of ZTOOLS.

                        HOW WE DO IT NOW

     MKDIR and LDR are the original tools provided by R. Conn for ì
maintenance  of  the  Named DiRectory  (NDR).  The  former  is  a ì
specialized  editor which creates or modifies files which contain ì
NDR  information.  The  latter loads such files into  the  system ì
named  directory buffer to provide names and passwords for  those ì
Disk/User areas that the user has chosen to define. When the user ì
wishes to redefine D/U name and password assignments,  he does so ì
by executing LDR to load a new .NDR type file from mass  storage. ì
He  might  wish to do this because the task at hand  has  changed ì
(i.e. from edit-assemble-link to data base management or to modem ì
communications)  or because a new floppy disk has been  installed ì
for which the directory names are not relevant.

                     WHAT'S WRONG WITH THAT?

     As convenient as this arrangement is,  it does imply a major ì
inconvenience  when the number of possible differently  organized ì
floppy  disks becomes significant:  the user must anticipate each ì
combination of disk-drive assignments and create an NDR file  for ì
each  one.  A little reflection will convince you that the number ì
of  NDR  files required grows geometrically with  the  number  of ì
drives available and the number of (differently organized) floppy ì
disks!  What  is  needed to alleviate this problem is a means  of ì
editing  selected  portions  of  the  system  NDR   buffer.   Two ì
approaches  suggest themselves:  1) replace the NDR entries for a ì
drive  with data from the disk currently installed in that  drive ì
and 2) edit individual entries (for ANY D/U) in the NDR.

.pa

                          ONE SOLUTION

     Wilson  H.  Bent  was  the  first  to  recognize  the  first ì
approach.  He  solved  the problem by providing the LDSK  utility ì
which  capitalizes on the common use of zero length  files  which ì
start with a '-' to identify directories for cataloging purposes. ì
LDSK  selects  those  names from the disk in  the  user-specified ì
drive to update the entries in the NDR for that drive.  The  idea ì
was  carried  a  step further by me in DSKNDR  by  including  the ì
ability  to also select the appropriate entries from an NDR  file ì
on the target disk. DSKNDR also recognizes the size of the system ì
NDR,  removing  the necessity of customizing it for those systems ì
which  require  more than the 14 entries allowed in  the  minimum ì
implementation.  See  the documentation for LDSK and  DSKNDR  for ì
more  details  on each.  (Incidentally,  DSKNDR is a  full  ZCPR3 ì
utility; the original version of LDSK was not.)

                 ANOTHER SOLUTION, ANOTHER ZTOOL

     The present program represents the second approach. It edits ì
individual entries in the system resident NDR. The editing may be ì
done from the invoking command line or in an interactive terminal ì
session.  WHY WOULD ONE WANT TO DO THAT? For one case, the use of ì
LDSK  or DSKNDR might result in duplicate directory names  (ROOT, ì
for example).   EDITND  can be invoked to change one of the names ì
to  something  unique.  LDSK does not provide  passwords;  DSKNDR ì
retains  passwords if they are present in an NDR files  that  was  ì
used.   In either case,  passwords may need to be added, deleted, ì
or  changed.  In  another  (less general) case,   the Sysop for a ì
Remote   Access  System  can use EDITND  to provide  a  temporary ì
password  for  access to  a directory for a specific  user.   The ì
operation  of a  RAS  is such  that the NDR may be  reloaded  for ì
each user,  replacing such dynamic  assignment.  That's  why they ì
are   temporary.   A   little imaginative reflection will  reveal ì
other usage scenarios.

     EDITND   was designed first,   THEN written.   Here are  the  ì
main design goals:

1) Make it a ZCPR3 utility;  use standard invokation & arguments. ì
In particular,  ?,/, and // always invoke HELP; /ooo... specifies ì
options.

2) Usage is restricted (by the Wheel byte) to privileged users.

3)  Invokation  from the command line with NO  undesired  console ì
output. (for secure systems)

4) HELP displays on demand.  Make sure that when the program name ì
changes, the Help screen automatically stays relevant!

5) Error messages displayed only if asked for by the user. (I get ì
offended at programs that 'chatter' at me!)

6)  Structured  and well commented source code.  When changes  or ì
debugging are required, these factors really pay off!

7) I know I'll forget some important function.  Therefore,  write ì
the  code so that it's not necessary to re-write the  program  to ì
incorporate   new   features.   Make  the  command  set   readily ì
extendable.

                        THE EDITND  PROGRAM

     Edits the System Named Directory.  Changes, adds, or deletes ì
directory  names and passwords.  The changes are to the  resident ì
Named Directory buffer, but may be aborted (restored to original) ì
if desired.
     Multiple commands on the command line or in interactive mode ì
are supported.  Commands on the invoking command line produce  no ì
unsolicited console output,  so this program can execute silently ì
in an alias or RAS environment.  In the interactive mode, command ì
errors  are  explained  only  on  request.  The  HELP  screen  is ì
automatically  maintained;  so  if  you change the  name  of  the ì
program,  the version number, or the command separator character, ì
the HELP information will remain relevant.

                       HOW TO INVOKE EDITND

     EDITND <cr>         Enter Interactive Mode, prompt user

     EDITND  <cr>        Same, but show current NDR first

     EDITND <commands>   Execute the commands, then enters
                         interactive mode. Commands are separated
                         by '\' which is the default command
                         delimiter.

   EDITND <commands>\x   The 'x' command means 'exit to the
                         operating system'. The interactive
                         mode is never entered. Useful in an
                         Alias, or when only a few changes are
                         to be made. The '\' is the EDITND
                         command separator.

     If  an  error condition occurs during execution of  commands ì
from the invoking command line,  the error code is placed in  the ì
ZCPR3 program error code byte.  There, it can be tested by IF.COM ì
and appropriate action taken.

.CP 15

     The   following  command  lines display  the  EDITND    Help  ì
screen  without   entering the  interactive  mode.   (i.e.   they ì
display help and then immediately exit to ZCPR3)

     EDITND  ?
     EDITND  /
     EDITND  //

     From  interactive  mode,  the  HELP commands  (?,/,//)  work ì
differently in several ways.  First, they do not cause an exit to ì
the  operating  system.  Second,  they are sensitive to an  error ì
condition  and  display the offending command  and  a  diagnostic ì
error  message.   Third,  the  error  code  associated  with  the ì
diagnostic is NOT sent to the ZCPR3 program error byte.

     A  complete  BNF-style  description  of  command  syntax  is ì
included below.  In plainer (but not as precise) English, here is ì
a summary of the commands with some examples:

RULES FOR FORMING COMMANDS:

You may type either upper or lower case. Mix 'em if you want.

'\' is the character which separates commands

leading and trailing spaces are ignored, except that at least
  one space must separate command arguments. Comma is NOT a
  substitute for a space in most cases.

A comma is permitted in certain cases to imply a default DIR
  preceding the comma, and a null (blank) argument after the
  comma. If you supply a dirname before the comma or a PW after
  the comma then these over-ride the default. See examples below.

<cr> means carriage return. As usual, nothing will happen until
  you enter a <cr> at the end of a command line.

DU means Disk/User, like a8, B3, etc. (note NO COLON. Use of a
  colon after the DU is entirely optional in EDITND )

DIR means a directory name that exists in the NDR. Again, a
  terminating colon is not required but is ok.

<dir> means EITHER DU or DIR may be used for this command. A
  colon MAY be used (DU: or DIR:) but is not required.

.PA

                     THE EDITND  COMMANDS


<cr>   Displays  the current NDR buffer contents.  If new entries ì
       have been added,  they will not be in sorted order.  Don't ì
       worry.  They will be when the program exits. If it bothers ì
       you, the 's' command will put them in proper order.
       This is an EMPTY command. A '\<cr>' at the end of a string ì
       of  commands,  or  '\\' within a string of  commands  also ì
       causes the current NDR to be displayed. (Just like PWD)

X      eXit  to the operating system after making sure  that  the ì
       NDR  is  in  order.   A  sort  is  done  automatically  if ì
       required  to  put  the entries into the normal order.

Q      Quit  to the operating system,   restoring the NDR to  its ì
       original  condition.  Any changes made during the  session ì
       are ignored.

R      Reset  the NDR to its original condition.  Any changes are  ì
       lost; you are starting over anew.

Z      Zap the NDR. All entries are erased. You can add new ones, ì
       if  you  wish.   The 'R' command gets  everything  (except ì
       changes)  back,  and  the 'Q' command leaves  the  entries ì
       restored.   If  you 'X' at  this point,  there will be  NO ì
       entries in the NDR.

S      Sorts  the NDR entries into the order that you're used to.        ì
       You  only need to do this for your  own  convenience.  The        ì
       program  will  automatically  sort  the  NDR  on  exit  if ì
       required.

/oo... The  slash  is the leading character for Option  commands, ì
       where  'o' represents options from list on the next  page. ì
       One  of the options is the letter 'O' (also '0',  in  case ì
       your terminal makes them both look the same). If you issue ì
       the  command  '/O<cr>' the same list will be displayed  on ì
       your console.  Multiple options may be given in any order; ì
       they are executed in the sequence in which you list  them. ì
       No  spaces are allowed in the option list,  since a  space ì
       terminates the list.


.PA



         COMMANDS to CHANGE, ADD, and DELETE NDR ENTRIES

<dir>                   deletes the entry
<dir>,                  deletes the password

to change an entry, the DU or DIR must already exist in the NDR
(if it shows in the NDR display, you can change it)
<dir>,pw                changes password to PW
<dir> new pw            changes both DIR and password
<dir> new,pw            changes both DIR and password
<dir> new,              changes DIR to 'new' & deletes password
<dir> new               changes DIR to 'new' (NOTE: no comma!)
                        and does not change any password

to add a new entry, the new DU must be specified
<newdu> name            adds a new entry, newdu:name, & no password
<newdu> name pw         adds a new entry, newdu:name, password=pw
<newdu> name,pw         comma is ok here instead of a space


                OPTION COMMANDS (preceded by "/")

       /       Display Help. If error, show error diagnostic
       H       Toggle display of help after error diagnostic
       B       Toggle audible notice of command error
       E       Toggle visual notice of command error
       S<ch>   Change command separator to character <ch>
       O       Display this screen of option selections
       C       Display the list of error codes

Option commands start with '/' and end with a carriage return  or ì
command  separator.  Multiple options from the list above may  be ì
included in any order. For example,

                            /hbeo<cr>

is  perfectly acceptable.   By default,   EDITND  will sound  the ì
bell  and   display   a message on the console to  serve   notice  ì
when   an  error  has  occurred.   If  you  then  ask  for   help  ì
(?,/,or//)  a diagnostic message will be listed,  followed by the ì
main body  of the  help  screen.  The example command above would ì
turn  off   the bell,   warning message,  and the automatic  help ì
display; then show the  above option list.  When no error exists,  ì
the  help   command  shows the help screen  regardless  of  these ì
options.   Note that  if you   assign  a  new   separator,    the  ì
assignment    takes     place  immediately,    and   your    next  ì
separator  must  be  the  one  you assigned!
.pa

*****************************************************************
The  remainder  of  this  documentation describes  EDITND    from  ì
a  programming  viewpoint,   and is not required in order to  use  ì
the  program.  If you want to see how the program works in detail ì
or  if you want to make changes in the  program,   the  following  ì
material  will  supplement  the comments in  the  program  source ì
itself.  I  hope  that   these  notes will  help  understand  the ì
programming  techniques and  data  structures  used  and  thereby  ì
inhibit  the  growth  of members  of  the  insect world.   Please ì
coordinate   any   proposed revisions  with  the original  author ì
and   help   prevent   multiple versions with  the  same  version ì
number!
                    Al Hawley, Ladera Z-Node, LA, CA
                    [phone] (modem), 649-3575 (voice)
*****************************************************************


               BNF TYPE COMMAND SYNTAX DESCRIPTION

<Command line> = [ <cmd> [ \ <cmd>...]]<cr>

<cmd> = <ltr> | <dcmd> | <ocmd>

  <ltr> = q | r | s | w | x | z | ? | / |<ucltr>

       <ucltr> = Q | R | S | W | X | Z | <mt>

         <mt>  = <carriage return> | <\[<sp>...]\>

  <dcmd> = <dir>[:] [, | ,<pw> | <name>,<pw> | <name><sp><pw>]

         <dir> = "a directory name of 8 or less characters" | <du>

         <du>  = <drive letter, a..p><one or two digits, 0-31>

         <pw>  = "8 or less ascii characters except delimiters"

        <name> = "8 or less characters (a new directory name)"

         <sp>  = a space

  <ocmd> = / [ <oc> [<oc>...] ]

          <oc> = / | H | B | E | O | C | S<ch>

          <ch> = "any printable character EXCEPT <ltr>|<oc>"
.pa

                     MAIN ROUTINE ALGORITHM:

1) Set up local stack, save system stack pointer

2) Initialize buffers, validate environment, save a copy of
the system NDR for use during an abort. Abort to operating
system with message if fatal error condition exists.

3) Transfer the command tail into the local command line buffer.

4) Do until (program exit condition)

      Do until (command line buffer empty) OR (exit condition)
          Transfer a command into single command buffer
          Parse command with ARGV
          Resolve  command logic using parameters to derive a key ì
            for the CASE call to the execution routine.
          If no error, execute the command via call to CASE
          If error, save error code & command in a history buffer
      End until (command line buffer empty) OR (exit condition)

      Issue prompt and get command if no exit condition

   End until (program exit condition)

4) Perform any required cleanup operations:
    Sort the system NDR if required
    Restore the system NDR from the saved copy if this is an
        abort and changes have been made.

5) Restore the system stack pointer

6) Return to the operating system

END OF ALGORITHM
.pa

                   COMMAND PARSE & RESOLUTION

ALGORITHM:
        Parse  the  command by counting arguments  and  analysing ì
each argument.  Based on the results,  assign a value to a  'key' ì
which uniquely defines the function to be performed.
        If the first argument defies recognition, record an error ì
and ignore the balance of the command.
        If  the  first argument comprises exactly  one  character ì
execute   the  appropriate  function  and  ignore  any  remaining ì
arguments. If the command character is not defined then record an ì
error and ignore the command.
        If  the first argument is a valid DU or DIR then  analyse ì
the  remaining  arguments and reduce the command to  the  general ì
form:  DU <dirname> <password>.  Substitute this reduced form  in ì
the   NDR if DU already exists there,  else append to the NDR  if ì
there is space available. If neither <dirname> nor <password> are ì
given in the argument list, then any existing entry in the NDR is ì
deleted.  When  a  ',' is present which results in  an  ambiguous ì
interpretation, record an error and ignore the command (cases 4 & ì
5).
        If  the  first  argument begins with '/' then  treat  the ì
remainder of the characters in that argument as special commands. ì
If  a  command requires an  argument,  the  argument  immediately ì
follows the command letter. Process each command character in the ì
order given. If no characters follow the '/' then consider this a ì
command  to  display the help screen.  On encountering an  error, ì
record the error and abort processing of the remaining options.
.PA

                        COMMAND ANALYSIS

arg1,  arg2,  etc,  are  Pointers returned by ARGV to the  first, ì
second, etc. arguments in the command.

Group  0:  The first argument is not a defined  du,  dir,  single ì
letter command, or a string starting with '/'.

arg1            arg2-arg4       action/comment

<unknown>       <don't care>    ignore command, record an error

Group 1: empty command, or single-letter command

arg1    arg2    arg3    arg4  case - action/comment

--      --      --      --      0 - display NDR & passwords
<ltr>   --      --      --      A - perform <ltr> function

Group 2: the first arg is a valid du|dir form

arg1    arg2    arg3    arg4  case - action/comment

<dir>   --      --      --      1 - delete entry from NDR
<dir>   name    --      --      2 - replace name/make new entry
<dir>   name    <pw>    --      3 - new name, new password
<dir>   ','     --      --      4 - delete (blank) password
<dir>   ','     <pw>    --      5 - change password
<dir>   name    ','     --      6 - new name, blank password
<dir>   name    ','     <pw>    7 - new name, new password

Group 3: The first arg begins with a '/'

arg1            arg2-arg4       action/comment

/[<str>]        (ignore)        case  9 - <str> is a sequence  of ì
                                characters  which define settable ì
                                options.   '/'   as   an   option ì
                                character    invokes   the   help ì
                                screen.

.pa

          CALCULATION OF CASE-KEY (ckey) FOR EACH CASE

a1code = (if single ltr) ascii (else) 0
a2code = (if arg2 = ',') 2 (else) 0
a3code = (if arg3 = ',') 3 (else) 0

        argnum  a1code  a2code  a3code  ckey=sum

case 0     0       0       0       0       0
case 1     1       0       0       0       1
case 2     2       0       0       0       2
case 3     3       0       0       0       3

case 4     2       0       2       0       4
case 5     3       0       2       0       5

case 6     3       0       0       3       6
case 7     4       0       0       3       7
case 8  (not defined)
case 9     >0      8       0       0       9 (argnum <- 1)
case A     1    ascii-1    0       0     ascii


                PROCESSING REQUIRED FOR EACH CASE

notes:  1) appflg = FALSE if d/u IS in the NDR, else TRUE
        2) xx -> yy means "make xx point to yy"
        3) xx <= yy means "make xx equal to yy"

        if appflg=F:                    if appflg=T:

case 0  display ndr                     display ndr
case 1  delete entry                    do nothing
case 2  arg3->dirpw                     arg3->spaces
case 3  replace NDR entry               append new NDR entry

case 4  arg2->dirname, arg3->spaces     do nothing(err)
case 5  arg2->dirname                   do nothing(err)

case 6  arg3->spaces                    arg3->spaces
case 7  arg3<=arg4                      arg3<=arg4

case 9  argnum <- 1, do option(s) or display help
case A  do ltr cmd                      do ltr cmd