ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/MBUG/MBUG037.ARC/LU.DOC

Text File | 1979-12-31 | 23KB | 666 lines

Documentation for LU.COM and LRUN.COM


This  document applies to version 1.10 of LU.COM and version
1.0 of LRUN.COM.

Copyright (c) 1982 Gary P. Novosielski
All rights reserved.

Permission  is  hereby  granted  to copy and distribute this
document  for  any  non-commercial  purpose. Any use of this
material  for  commercial  advantage  without  prior written
consent of the author is prohibited.



                        INTRODUCTION

Lubrary  Utility  (LU)  is  a  program to allow combining of
multilple  files  into  one  larger  file.  It requires CP/M
version  2.0  or  higher  to  run.  LU  was  developed as an
alternative  to  the excellent ARCHIVE series of programs by
Michael Rubenstein. The major differences are:

     LU  was written mostly in the BDS implementation of the
C  language,  with substantial reduction of object code size
as  compared  with  the  ARCHIVE programs. The add, extract,
delete,  list/map, and reorganize functions are all combined
in one object program of less than 20k.
     The directory information is stored in the same file as
the  data,  or  member  files.  The  amount  of  space to be
allocated  to  the  directory  must be specified by the user
when  a  new library is created, but can be changed when the
file  is reorganized. The size of each directory entry is 32
bytes,  which  means each four directory entries take up one
sector  of the library file. Currently only 16 bytes of each
entry  are  used,  with 16 bytes being reserved for use with
possible  future enhancements. The directory itself uses one
entry  for  control  information, so the number of directory
sectors  needed  for  a library of m members is (m + 1) / 4,
rounded up to the next whole number.
     The  user need not be concerned with this discussion as
directory  size  is calculated by the program. All directory
sizes  are  input and output in terms of entries, each entry
being a potential member file. The program adjusts directory
size to an integral number of sectors.

     LRUN.COM  is  a  small (12 sector) program which allows
running  a  .COM (object code) file member directly from any
library,  without  having  to  extract it to a separate disk
file.










Page 1   82-08-07




Documentation for LU.COM and LRUN.COM


                     WHY USE LIBRARIES?

     First,  a library file usually takes up less space than
the total of the individual member files which went into it.
The  reason  for  this  is that CP/M allocates disk space in
fixed  blocks  or groups, typically 2k bytes each. Any space
after  the  last  sector  of  a file up to the next 2k block
boundry  is wasted. The same files in a library use only the
number of sectors they actually need, and though the library
itself  may  have  a  partially wasted block at the end, and
requires   some  space  for  directory  information  at  the
beginning,  the  net  effect  is  usually  a saving of total
space.  The  best results are seen when many small files are
combined into one library.
     Second,  a library file makes most efficient use of the
CP/M disk directory, since it is treated as only one file by
CP/M regardless of how many members it contains.
     Third,  libraries  can  aid in transferring packages of
software  from  one system to another using XMODEM. Only one
file  is transferred, eliminating the need to run the XMODEM
transfer  program several times, the chance of overlooking a
needed  file, and the problems of naming conflicts, (such as
READ.ME files) among unrelated packages.



                   WHY NOT USE LIBRARIES?

     There   are  some  very  good  reasons  for  not  using
libraries.
     For one thing, files within a library are not available
to  most "normal" programs. If a frequently accessed file is
placed  in  a library, it will have to be extracted from the
library  to  its  free-standing counterpart before it can be
used  by  a  program. (.COM files are a notable exception to
this,  because  of  the  availability  of  the LRUN command,
covered later.)
     Libraries  can  actually  waste disk space. When a disk
file  is erased, CP/M returns the space formerly used by the
file  to  the  free  space pool for use by new files. When a
member  file  is  deleted  from a library however, the space
previously  occupied by the file is not useable. The library
must  be  reorganized  to make this space available to CP/M.
While  this  is  easy  to  do with the LU command, it is not
automatic,  and  if the situation is ignored, large areas of
disk can be tied up as unproductive "dead space".












Page 2   82-08-07




Documentation for LU.COM and LRUN.COM


               HOW TO USE THE LIBRARY UTILITY

     LU has two basic methods of operation: interactive, and
parameter  driven. Use of the interactive method is probably
the  best way to get to know the program, because the effect
of each action can be immediatley seen.
  To  start an interactive library maintenance session, just
type  LU  on  the  command line with no parameters after it.
After  you  are  familiar  with the program, you can specify
multiple paramters on the command line and LU will work with
little  or no intervention. Input from disk files, C program
"pipes",  and  the XSUB facility are also supported for more
advanced applications.
     All  the  methods  make  use of similar syntax. Command
input  takes two forms: operators (sometimes called tags, or
options) and operands.
     An  operator  is  defined  as  any two character string
where  the  first  character is a minus sign. Operators tell
the  program what to do. Valid operators are -a, -d, -e, -l,
-o, and -r. Anything else with a similar form is an operator
too, but an invalid one.
     Operands  are  everything  else. Normally, operands are
file names which you want to add to, delete from, or extract
from  a  library  file,  or are names of library files to be
opened. They may contain the characters * or ? in which case
they are called ambiguous operands. Some valid operands are:

 foo.bar
 b:test.fil
 z
 *.*
 comm?nd

 etc.  To  refer to a file named "-z" the operand would have
to  be  entered as "-z." with the period, since otherwise it
would be mistaken as an invalid operator.
     What  action  is taken upon the file depends upon which
operator  most  recently  preceded  it.  If  no operator was
entered,  or  an invalid one, or one that takes no operands,
the operand will be ignored.
     When running interactively, LU prompts for each operand
and  operator,  one per input line. Multiple inputs per line
are not allowed using the interactive method.
     The  prompt  you  will  see  is the name of the current
operator  followed  by  a  ">" character, for example "-E>".
This  indicates that the -e operator is in effect, and if an
operand  is  entered it will be interpreted as the name of a
member  file  to  be  Extracted  from  the library. When the
program  first starts up, the prompt is "-?>" which means no
operator  is  currently  in  effect.  In this case, the only
valid input is an operator. Any operand will be ignored.







Page 3   82-08-07




Documentation for LU.COM and LRUN.COM


                    SUMMARY OF OPERATORS

     -a   add  files  to  library.  -a  causes the prompt to
change  to  -A> which will then accept as operands the names
of  files  to  be  added to the open library. (If no library
name  has  been  opened  with  the  -o operator, the default
library  LIBRARY.LBR  is  always  used  instead.)  Ambiguous
operands  match  all  disk  files which qualify according to
normal  CP/M  wild-card  conventions,  except  those  with a
filetype of .LBR. Explicit drive specification on an operand
causes  that drive to be searched for the file(s) instead of
the current drive.

     -d   delete files from library. -d causes the prompt to
change  to  -D>  which  accepts names of files to be deleted
from  the  open  library.  Ambiguous  names match all member
files  which  qualify.  Drive specifications on operands are
ignored,   since   the  library  members  are  obviously  on
whichever drive contains the open library.

     -e   extract  files  from library. -e causes the prompt
to change to -E> which accepts names of library member files
to   be   extracted  to  normal  free-standing  CP/M  files.
Ambiguous  names match all member files which qualify. Drive
specification  on a member name causes the output file to be
placed on the specified drive rather than the current drive.
Any  existing  file  with  the same name will be overwritten
unless  it  is protected by virtue of its Read/Only flag bit
being set.

     -l   list  current library map. -l causes the directory
of  the  current  library  to  be listed on the console. The
member  names  are  displayed,  along  with  their index, or
starting  position  within  the  library,  and their size in
sectors.  Also, information is displayed about the number of
sectors  in  the  library,  and  how  much space, is used or
unused  (wasted).  Information  is  also displayed about the
number of entries in the directory, and how many are active,
deleted,  or  free for use. This helps determine whether the
library  needs  to  be re-organized to free unused space and
deleted  entries.  The  operator  -l expects no operands, so
after  the list is displayed, the prompt changes back to -?>
for entry of another operator.

     -o   open  a library. -o causes the prompt to change to
-O>  which  accepts  the name of a library file to be opened
for  use  with  subsequent  operators. If another library is
already  open,  it  is closed first. If the new library does
not  exist, it is created with an empty directory. Ambiguous
names  are  not allowed. Drive specification is allowed. The
file  type  may  be specified, but defaults to .LBR which is
strongly suggested as the file type for all library files.
     You  will  recall that files of type -a (add) operator.
This  prevents  libraries  from  being accidentally added to
other  libraries,  or  to themselves; a situation not unlike
trying  to  drive  a  truck up its own tailpipe. If for some


Page 4   82-08-07




Documentation for LU.COM and LRUN.COM


reason  you want to add one library to another, be my guest,
but  you  will  have  to  specify  the  name  without * or ?
characters when adding it.

     -r   reorganize  library.  -r causes the currently open
library  to  be  reorganized. First, the directory is sorted
into  alphabetical  order,  and  then all active members are
copied  to  a  work  library  which is opened on the current
drive, not necessarily the drive containing the old library.
The  user  may specify a different number of entries for the
work  library  if  it is necessary to expand or compress the
directory. The directory will always be made large enough to
contain all the active members of the old library, so a size
of  1  may  be  specified  to make the directory as small as
possible. (See Specifying Directory Sizes below.)
     When  reorganization  is  complete,  the old library is
deleted  and  the work library is renamed to the name of the
old   library.   No  backup  copy  is  retained.  The  newly
reorganized  library  remains  open  for use with subsequent
operations.

   Whenever the program is prompting for an operand, another
operator  may be entered instead to change the status of the
prompt. To end an interactive session, enter a blank line at
the prompt.



                 SPECIFYING DIRECTORY SIZE

     Whenever  an  old library is opened, the directory size
is displayed as follows:

 Old library LIBRARY.LBR has 32 entries, 5 free.

     This  means that 5 more members may be added before the
directory  becomes  full.  When  the  directory  is full, -a
becomes  an  invalid  operator,  and  the  library  must  be
reorganized to add any more members.
     When  a library is created for the first time, the user
is prompted like this:

 New library COMMAND.LBR. Allow how many entries?_

     Any number from 1 to 65535 is valid. The actual maximum
is  determined by the amount of free memory available on the
system in use. Directory size will be rounded up to the next
whole  sector  necessary  to  contain  the number of entries
requested.  This  number  will  remain  in  effect until the
library is reorganized. Since the directory itself counts as
an  entry,  one entry is added to whatever is entered before
the  size  is  calculated.  Therefore just enter the maximum
number of member files you want the library to be capable of
holding.
     The  maximum number of member files is also constrained
by  the  amount  of  available  disk space. If during an add


Page 5   82-08-07




Documentation for LU.COM and LRUN.COM


operation  the disk space runs out, the name is not added to
the  directory.  If a multiple add is in progress, due to an
ambiguous  operand, the remaining qualifying files are still
added  if possible. If any of them is small enough to fit in
the  remaining  disk space, it will be added. If any sectors
were  written  by  an  add attempt, and then never utilized,
they  remain  as  unused  sectors, and the library should be
reorganized.



                  PARAMETER DRIVEN METHOD

     All of the information needed for a maintenance run may
be specified on the command line. The operators and operands
are  entered, separated by spaces, after the LU command, and
the operations will take place without console intervention,
except  in  the  case  where  the  directory  size for a new
library is requested. The syntax is:

 LU <opr> [<opd> [<opd> ...]] [<opr> [<opd> ...]...

 where square brackets indicate optional parameters, and:
     <opr> is any operator.
     <opd> is any operand.
     ...   indicates  that the preceding parameter may occur
multiple times.
     Any  names  occurring  prior  to the first operator, or
following  an  operator  which does not expect operands, are
ignored.




























Page 6   82-08-07




Documentation for LU.COM and LRUN.COM


                     ADVANCED FEATURES

     Input  from  BDS C "pipes" or ordinary sequential files
is  also  possible. The filename is specified on the command
line  preceded  by a "<" character and no intervening blank.
Example:

 LU <CONSOL.DUP
     reads the contents of the file CONSOL.DUP and uses each
line  of  the  file  as  if  it had been typed at the normal
console   by  the  interactive  method.  In  this  case,  no
operators  or  operands  may  be present. Console output may
also  be  redirected  by  specifying  an  output file on the
command  line  after  the  character  ">".  This  applies to
parameter  driven as well as interactive (including "piped")
input. Examples:

 LU -O SPECIAL -A ZOT.COM >LOGFILE.OUT
     would  add  the file zot.com to the library special.lbr
and  write  the console output to a file called logfile.out.
the  location of the output name on the line does not matter
and  except  for turning on redirected output, it is ignored
by all operators.

 LU <BATCH.IN >B:RECORD.DOC
     would  take interactive commands from the file batch.in
and  write  console  output  to  a file called record.doc on
drive B.

     Normally,  console  file  output  is also echoed on the
real  console,  except  when input is also redirected, as in
the  last example. To force visible console output when both
an  input  and  output  file  are  used,  the  ">" character
preceding  the  output  file  name  may  be changed to a "+"
instead:

LU +RECORD.DOC <BATCH.IN
     would  have  the  same  effect as the previous example,
except  that  message  output  would  also be visible on the
console.




                          CAUTIONS

    The  importance  of  keeping  backup  copies of all disk
files,  and  especially libraries, cannot be overemphasized.
By  using  library files, the user is exposed to the dreaded
all-the-eggs-in-one-basket  syndrome.  That is, if something
happens  to the library file, particularly the directory, it
may  be  beyond  the  capabilities  of even a CP/M wizard to
restore the member files. The situation is made particularly
sticky by the fact that the the directory must be updated in
place as members are added or deleted.
     Precautions  have been taken to minimize this risk. For


Page 7   82-08-07




Documentation for LU.COM and LRUN.COM


one  thing,  the  directory  is  read  into  memory when the
library  is  first  opened,  and  is only written back if it
differs  from  the  copy  on  the  disk  when the library is
closed.  Operations  which  change  the directory are: adds,
deletes,  and  the  sort  operation  which  is  done  before
reorganization.   If   only   extracts   (or   LRUN  program
executions)  are done, the directory is never rewritten, and
the .LBR file may be write protected if desired.
     For  another  thing,  the  entire  empty  directory  is
allocated  and  written  to disk when a new library is first
created. This insures that there will always be enough space
on disk for the number of directory entries requested at the
time  of  creation.  The disk space may run out while adding
files later, but there will always be enough room on disk to
update the directory once it is successfully created.
     The  fact that only the memory copy of the directory is
modified  until the file is closed may come in very handy if
you  mistakenly  delete  a file and recognize it right away.
For  example,  suppose  you  make  the mistake of typing *.*
after the -D> prompt.
     Briefly,  your  heart sinks, as the "Deleting:" message
is  displayed  and  all  the member names zip into oblivion.
Don't  panic. Only the memory copy of the directory has been
modified.  When  the  -D> prompt returns, do not hit RETURN.
Instead,  abort the program with Control-C. This will cancel
the program without updating the directory, and the original
members will still be present.
     Here  is  another  caution.  Since the entire directory
(but not member sectors) must fit in memory for a library to
be successfully opened, it is possible that a huge directory
created  on a your system will be too large to fit in memory
if  read on another system will less memory. This should not
be a problem with a library of under a hundred entries.
     To  give  you an idea of how much elbowroom you have to
work with, LU displays the highest memory location used each
time  it terminates. This will vary depending on the largest
directory  used  during  operation.  It does not include the
stack,  which  grows  down  from high memory, and is allowed
about  a thousand bytes of space for subroutine linkages and
temporary work areas.


















Page 8   82-08-07




Documentation for LU.COM and LRUN.COM


                      THE LRUN COMMAND

     The  LRUN  command was created for those of us who have
lots  of command files we like to keep on line all the time.
What usually happens is that some nice little .COM files are
very  small  programs, but having a lot of them on disk eats
up  file  space  at  an  alarming rate due to the fixed CP/M
block  size.  Put them all into a library called COMMAND.LBR
using  LU.  You can then run any .COM file directly from the
library by saying:
 LRUN <followed by normal command line just like always>
    The full syntax of LRUN is:

 LRUN [-<lbrfile>] <commember> [<parameters>]

Where:

     <lbrfile>  is  the  library  to be searched. The square
brackets  around  -<lbrfile>  indicate it is optional. The -
character tells LRUN that what follows is a library name. It
is not an actual part of the name. Don't leave a space after
the  -. If the first parameter doesn't begin with - then the
default  library  COMMAND.LBR  is  used.  If a drive spec is
given,  such as B:, then only that drive is searched for the
library.  If  no  drive  spec is given, the current drive is
searched first, and if no library of that name is found, the
A:  drive  is  searched  before giving up. If a name, but no
type is entered, .LBR is assumed.

     <commember>  is  the  name of the command to be run. No
drive  spec is used here. The type defaults to .COM and need
not be entered.

     <parameters>  is  a the normal (possibly empty) list of
parameters  which  the  .COM  file  expects  to  find on the
command  line  when  it  is  run. This list is parsed to the
required  file  control  blocks and command line area before
execution  begins,  so  the  program  will not be aware that
anything  cute  is  going  on. (Thanks to Ron Ron Fowler for
supplying the code which makes this possible.)



                       LRUN EXAMPLES

 LRUN ED FOO.BAR
     the  file  ED.COM is searched for in COMMAND.LBR on the
current  drive,  or the A: drive. If found, ED.COM is loaded
from  the  library,  and  FOO.BAR  is  passed  to  it  as  a
parameter.

 LRUN -C:SPECIAL LU -O COMMAND -A A:*.COM
     the file LU.COM is searched for in SPECIAL.LBR on the C
drive.  If  found,  LU.COM  is  loaded,  and the strings -O,
COMMAND, -A, and *.COM are passed to it as parameters.



Page 9   82-08-07




Documentation for LU.COM and LRUN.COM


 LRUN - -ZIP
     the file -ZIP.COM is searched for in COMMAND.LBR on the
current drive, or the A: drive. If found, -ZIP.COM is loaded
and  executed  with  a  blank parameter list. Since -ZIP.COM
begins  with a -, the extra - followed by a space was needed
to act as a place-holder for the library name. Compare with:

 LRUN -ZIP
     the  library  -ZIP.LBR  is looked for, but nothing else
happens, because no command was specified.

 LRUN
     with  no  parameters  at  all,  causes a screen of help
information to be displayed as a memory refresher.



     Please   report   any   problems   or  suggestions  for
enhancement  to  me  via  CompuServe  EMAIL  or CP-MIG, user
number  70160,120;  or  by  phone  at [phone], voice,
evenings (eastern) or weekends.

                    Gary P. Novosielski



































Page 10   82-08-07


            Gary P. Novosielski