2000
INTRODUCTION: THE LIBRARY CONCEPT
LU Command Conventions
SUMMARY OF LU OPERATIONS
  Looking Over Existing Libraries: LDIR
  Unpacking Entire Libraries: LUNLOAD
  Selecting Libraries for Access: -O
  Accessing Individual Members in Libraries: -L -E
  Executing Programs in Libraries: LRUN
  Building and Maintaining Libraries: -D -N -A -R
  Finishing Up: -C -X
HANDLING SPECIAL SITUATIONS
  Insuring Enough Memory Capacity: -B
  Changing Drives and Switching Disks -- Precautions: -U
  Staying Out of Trouble: Error Recovery
HOW LIBRARIES ARE ORGANIZED
:LU 3.00c             NOTICE: Current Version Numbers          dh: 84-01-15
                      ===============================

     This material applies to version 3.00 of LU.COM.  Libraries created by 
LU 3.00 can be read by all previous versions,  and vice versa,  but version 
3.00 provides additional protection against undetected damage in files that 
it creates and accesses.


                Copyright 1982, 1983 by Gary P. Novosielski
                           All rights reserved.

     Permission is hereby granted to copy and distribute this work for  any 
non-commercial  purpose.  Any use of this material for commercial advantage 
without prior written consent of the copyright owner is prohibited.  Please   
report  any  problems  and suggestions for enhancement to  the  author  via  
CompuServe  CP-MIG or EMAIL posting to user number 70160,120;  or by  voice 
phone to (201) 935-4087, evenings (eastern time) and weekends.

     LU.HLP #3.00a first derived by Dennis E. Hamilton on 83-10-30.

                                                     next: What is a Library?
                     INTRODUCTION: THE LIBRARY CONCEPT
                     =================================

     Library  Utility  (LU)  is  a  system for  storing  several  files  as 
components of one larger file.   The resulting library (.LBR) file has  its 
own PRIVATE DIRECTORY.  

     Library  files  provide an additional dimension  for  the  collection, 
organization, and maintenance of your work.  And because of CP/M disk-usage 
rules,  libraries  tend  to require less space than the same  files  stored 
separately.  In addition, libraries release CP/M disk-directory entries for 
other uses, especially when the library holds many tiny files.

     The maximum number of components -- library MEMBERS -- to be contained 
in  a library must be specified in advance.   But the limit can be  changed 
later on when the library is re-organized.

     Because  library members are tucked away within  other,  larger,  CP/M 
files,  they  have to be extracted -- taken off the shelf -- in order to be 
worked  on  or  used by typical programs.   The modifed  results  are  also 
restored to the library by using LU.
                                                  next: How LU Utilities Help
     To  make it easy to keep executable routines in  libraries,  the  LRUN 
utility is provided.  LRUN is a small program which will execute your .COM-
file programs directly from the libraries which hold them.   With LRUN,  it 
is  not  necessary  to extract a program into a separate disk  file  before 
execution.  

     Also, when material is packed in a library for convenient distribution 
in one piece, there is another utility, LUNLOAD, which unpacks everything.

     The basic library utility,  LU, lets you start new libraries and

   * Add new members to any specified library as long as there is room
   * Extract copies of any members for use outside of the library
   * Delete and rename members, as needed
   * Reorganize a library to change its capacity and recover deleted space.
   * Produce a directory to any library's current content.

     The utility LDIR allows inspection of a library's directory and  there 
are  variants,   such  as  LRUNZ  and  LDIRZ,  that  support  the  extended 
conventions  of ZCPR2.   There is a trend to have newer CP/M utilities also 
accomodate .LBR files in their operation.
                                                        next: Why (not) to LU
 WHY USE LIBRARIES?
   * Libraries make more compact use of disk capacity.
   * Libraries  require  fewer  disk-directory  entries,  cutting  down  on 
     clutter and releasing entries for other purposes.
   * Libraries  aid  the transfer of software from  one system to  another.  
     Only  one file is distributed,  reducing the chance of  omissions  and 
     oversights.
   * Libraries allow more flexible choice of file names,  since  uniqueness 
     is important only within each separate library.

 WHAT IS THE PRICE?
   * Files  within a library are unavailable to "normal" programs.  A  file 
     will usually have to be extracted from the library before its data can 
     be used.
   * When a library member is deleted,  space is not automatically released 
     for re-use.   The library must be explicitly re-organized in order  to 
     recover the directory entry and space of a deleted member.

On  balance,  LU lends tremendous support for disciplined organization  and 
maintenance of your programs and data.
::LUCMD                   LU COMMAND CONVENTIONS
                          ======================

     LU is guided by a miniature language of COMMAND-STRING OPERATIONS.  If 
you  are  unfamiliar with the notation and conventions of this tidy  little 
language,  you  should  locate the file LUCMD.HLP and review it  using  the 
command 

               a>HELP LUCMD

There you will find out about 

     * Different ways of initiating LU and supplying command string
     * General format of the command-string: use of spacing and line-breaks
     * Notation for specifying operations
     * Notation for selecting files
     * LU place-keeping and default assumptions
:                        SUMMARY OF LU OPERATIONS
                         ========================

OP OPERAND(S)       OPERATION

-A file-spec ...    Add the selected files to the open library.
-B s                Set the buffer size to s (1 to 255) records.
-C                  Close any library that is presently open. 
-D file-spec ...    Delete selected files in the open library.
-E file-spec ...    Extract selected files from the open library.
-L                  List a directory for the open library.
-N new=old ...      Rename selected files in the open library.
-O file-spec        Close any open library and open the specified one.
                    If the library does not exist, one will be created.
-R                  Re-organize the open library.
-U [u/][d:]         Close, change to the given defaults, and reset the disk
-X                  Exit from LU after the current line is processed.
                    An empty command-stream line implies -X.

In  a pinch,  you can ABORT processing with ^C at the input  prompt.   This 
leaves the open library directory as it was at the end of the last -C,  -O, 
-A, -R or -U operation.  Do -L and cleanup as needed, following with -R.
::LDIR                LOOKING OVER EXISTING LIBRARIES
                      ===============================

     When all you want to do is find out,  or remind yourself, what is IN a 
library,  the LDIR utility (and LDIRZ,  its ZCPR2 counterpart) are just the 
ticket.

     Typically,  LDIR lets you examine a library via a specification of the 
form

          d>LDIR library ...

     where  library identifies the library that you want to know about

     Command "d>LDIR COMMAND will,  with this convention,  show  everything 
that is known about files in library COMMAND.LBR.  For specific information 
about  the version of LDIR available on this system,  you should locate the 
file LDIR.HLP for review via 

               d>HELP LDIR
::LUNLOAD               UNPACKING ENTIRE LIBRARIES
                        ==========================

     When  a library file is used as a "carton" for a group of files  being 
distributed  together,  there is an easy way to make separate copies of its 
entire content:

               a>b:LUNLOAD c
2000
:library

will, for example, "unpack" the files of c:library onto the a: disk.

     Precise  operation  of  the  currently-supported  LUNLOAD  version  is 
specified in the file LUNLOAD.HLP.  Locate that file and review it via

               a>HELP LUNLOAD

     Note that the functions of LUNLOAD can be obtained with LU, but not so 
directly.   Also,  LUNLOAD may succeed where LU is unable to obtain  enough 
storage for operation. 
:                    SELECTING THE LIBRARY TO ACCESS
                     ===============================              

     Unless you are willing to use a library of name LIBRARY.LBR,  you need 
to specify the actual library to use with an OPEN command-string sequence:


               -O  library

        * Any library file that is already open will be closed.

        * The default u/,  d:,  and file type .LBR are used to complete the 
          library filespec, as necessary.

        * If  the  specified library exists,  it is opened for use  as  the 
          current library.

        * If  the  specified  library  does not exist,  a  NEW  LIBRARY  is 
          created.   LU will request information from the console in  order 
          to  allocate a library with sufficient capacity for the  intended 
          members.   (Refer to the information on "Building and Maintaining 
          Libraries" for further treatment of this case.)
:                     ACCESSING MATERIAL IN LIBRARIES
                      ===============================

     In  addition to using an LDIR utility,  you can review the contents of 
the currently-open library using the LU command-string

          -L

for "LISTING" the library directory while LU is operating.  

     When you need to work with separate copies of members, the LU command-
string
          -E filespec ...

"EXTRACTS"  copies  of those members selected by each  following  filespec.  
Every  library member that matches a single filespec is copied.   The  copy 
has the same filename as the original member.

     WHERE  copies  go  is  determined by  the  u/d:  determined  for  each 
filespec.  (Read-only files cannot be overwritten in this way, however.)

                                    next: Understanding the Library Directory
                         LIBRARY DIRECTORY ENTRIES

     The  information presented in response to the -L operation consists of 
the following:

           filename for   each  current  member  (and  DIRECTORY  for   the 
                    library's own directory space)

              index of  the library record where the member starts  (needed 
                    by the library utilities in finding the data)

               size of the member in CP/M RECORDS (128-byte units).  Divide 
                    by 8 for size in 1k units.
 
                CRC a  special kind of check code carried for  each  member 
                    and  used to help detect the presence of damage to  the 
                    library

     In  addition  to  this information  about  the  "active"  entries,  LU 
indicates  how  many members can be added and how many deleted members  and 
deleted records are cluttering the library.  (The waste for deleted members 
is eliminated by reorganizing with -R.)
::LRUN                EXECUTING PROGRAMS IN LIBRARIES
                      ===============================

     Usually,  library  data that is going to be used by a program must  be 
extracted first.

     But programs that are kept in libraries can be executed without having 
to  be removed first.   This is accomplished by use of the LRUN utility  or 
one  of  its kin.   For more information on the current  release  of  LRUN, 
locate the file LRUN.HLP and review it by

               a>HELP LRUN
::LBRBUILD          BUILDING AND MAINTAINING LIBRARIES
                    ==================================

     With a set of well-organized libraries in hand, most access will be in 
order  to  USE the material that the library contains.   LU  supports  this 
effort as do the more-specialized utilities such as LDIR and LRUN.

     But  LU is also designed to be used in constructing and modifying  new 
libraries of your own material.  

     Once you are comfortable with the general concepts of LBR-usage and LU 
operation, the additional provisions for building libraries will be easy to 
grasp.    The  file  LBRBUILD.HLP  describes  these  additional,   advanced 
features.  You can review it with the command

               a>HELP LBRBUILD
:                              FINISHING UP
                               ============

     When operations on a library have been finished,  there are three ways 
to move on.  Command-string

            -C will  "CLOSE" any currently-open library,  if there is  one, 
               making sure that all changes are reflected in its directory.  
               There is now no current directory.

            -X has  the same effect as -C,  followed by termination of  LU, 
               UPON COMPLETION OF THE CURRENT COMMAND-STRING LINE

     The  end  of  the command-string,  or the occurence of an  empty  line 
within it, has the same effect as the -X operation.
:                       HANDLING SPECIAL SITUATIONS
                        ===========================

     There are three areas where operation of LU can become tricky.  First, 
it  is  possible  to  exceed the capacity of your  computer  in  trying  to 
manipulate a library with allowance for a great number of members.   The LU 
operation 
               -B nn

may be used to obtain relief in some cases.

     Also, when it is necessary to change disks in the course of working on 
a library, there are some special precautions involved.  The LU operation

 
              -U [u/][d:]

helps to reset things properly after changing disks, when possible at all.

     Finally,  use  of .LBR files puts a lot of eggs in one basket.   There 
are  some  useful  tips available for making sure that the  .LBR  does  not 
go the way of Humpty Dumpty.
::LBRSIZE             INSURING ENOUGH MEMORY CAPACITY
                      ===============================

     Besides the space taken for program and housekeeping during LU  opera-
tion,  there  are two large data buffers:  one for DISK ACCESS and one  for 
LIBRARY DIRECTORY.

     If  your  CP/M system has a very large TPA (transient  program  area), 
there  is  not  much to worry about.   But you should  still  review  the 
capacity  rules   to  get a sense of the headroom available.

Command string:               -B nn

changes  the  disk-access  buffer  allocation to nn records  as  a  way  to 
increase performance or to accomodate a larger directory instead.  Complete 
details   about  this  and  related  adjustments  are  found  in  the  file 
LBRSIZE.HLP.  You should review this file with command

                         a>HELP LBRSIZE
:                   CHANGING DRIVES AND SWITCHING DISKS

     NEVER REMOVE OR CHANGE ANY DISK ON WHICH THERE IS AN OPEN LIBRARY.  LU 
carries information about the library in computer memory.  This information 
is not recorded on the disk until the last possible moment.   If you change 
a  disk without giving LU a chance to bring the disk and memory  copies  of 
data  into  agreement,  OPERATION WILL FAIL.   THERE IS THE POSSIBILITY  OF 
DAMAGE TO MATERIAL RECORDED ON ONE OR MORE DISKS.

     The  way to guarantee that all disks are in a "clean" condition is  to 
CLOSE THE CURRENT LIBRARY with the -C operation.   (If you are all done, -X 
does this too.)  You can now remove and replace disks as desired.

     To continue (when there is no CON: redirection), try operation

               -U filespec ...          

to  "log"  into  the new u/ and d:  defaults  specified  in  the  following 
filespec(s).   The  filespecs  should have only the u/ and  d:  fields,  as 
needed.   IF CONDITIONS ARE SAFE for -U, LU will close any current library, 
reset  the disk system,  and change the default para
480
meters.   You  can  now 
(re)-open the library to use next. 
::LUTIPS          STAYING OUT OF TROUBLE: ERROR RECOVERY
                  ======================================

     When  you are building,  modifying,  and  re-organizing  libraries,  a 
n
umber of problems can "spoil" an entire library's worth of work.   Tips on 
protecting your investment in library-stored material have been compiled in 
the file LUTIPS.HLP.  The file can be reviewed, once located, using command

               a>HELP LUTIPS
::LBR                   HOW LIBRARIES ARE ORGANIZED
                        ===========================

     .LBR files are organized in a special format that is only intelligible 
to  special-purpose  utilities  such  as  LU,  LDIR,  and  LRUN.   So  that 
specialists  can incorporate .LBR access into other utilities,  the  format 
rules  have been compiled in the file LBR.HLP.   If you have access to this 
file, you can review it with the command

                         a>HELP LBR
:
:
:
:    LU.HLP #3.00 was first created on 83-10-30 by Dennis E. Hamilton.

0

