;
                                    LD 
                                Version 1.4

                               Gene Pizzetta
                              March 21, 1992

LD is a ZCPR3 library directory utility that shows member files along with 
their create and modify dates and times, sizes, compression method, 
uncompressed filenames, CRC's, and indexes.  Embedded comments up to 76 
characters can be displayed.  Output can be directed to the printer.  
Message register output, file output, and wheel protection are included.  
It will also run under vanilla CP/M 2.2 and CP/M Plus, but only the current 
user is accessible and, of course, the ZCPR3 features will not work.

           U  Usage                         E  Errors
           O  Options                       C  Configuration
           D  Displays                      H  History
           S  Security                      B  Bug Reports
:U

                                   USAGE 


     LD {dir:}lbrname {afn} {{/}options}


If no DIR or DU specification is given, the current drive and user are 
assumed.  If an ambiguous file specification is given following the library 
name, only member files matching it will be shown; otherwise, all member 
files will be shown.  A member filename beginning with a slash can be 
matched by preceding the filename with a colon.
:O

                                  OPTIONS 

A leading slash is required only if the options are not the third token in 
the command tail, but is allowed in any case.

     A    Don't sort directory alphabetically.  Normally the library member 
          files are displayed in sorted order.  With this option the 
          members are listed in the order they appear in the library.

     C    Show embedded comments.  Some crunched files have a text comment 
          embedded in their headers.  This option will display them in 
          highlighted video on the line following the member listing.  This 
          option is ignored if the X option (alternate display) is used.

     D    Prefer embedded date stamps.  Ordinarily, LD checks the library 
          directory for a date stamp and, if one is not found there, it 
          looks for an embedded stamp in the headers of crunched files.  
          The first stamp found is displayed.  With this option, LD will 
          first check for an embedded date stamp and use the library 
          directory stamp only if an embedded stamp is not found or if the 
          member file is not crunched.

OPTIONS (continued)

     X    Alternate display.  Two member files are shown per line with 
          their CRC's and indexes.  Compression method, date stamps, and 
          uncompressed member names are suppressed.  Embedded comments 
          cannot be displayed.  Since no member file headers are read, LD 
          works faster than with the default display.

     S    Summary only.  Only the final summary line is displayed giving 
          statistics for the library as a whole.  Since individual member 
          files are not accessed, the summary is displayed very quickly.

     P    Don't page screen.  Normally, LD waits for a key to be pressed 
          each time the screen fills.  With this option scrolling is 
          continuous.  The screen can still be paused with ^S.

     Q    Quiet mode.  Only error messages are displayed on the console.  
          This option is very useful when LD is being used only to load the 
          message registers (option M).  It also allows sending the display 
          to the printer without echoing it to the screen.

OPTIONS (continued)

     M    Store results to memory.  The number of matching member files and 
          the number of free (unused) library directory entries are stored 
          in two two-byte words (low byte first) in four consecutive 
          message registers.  As distributed, registers 18 through 21 are 
          used.  LD's operation can be greatly speeded up if the S option 
          is used with M.

     L    Echo to printer (LST:).  Printer output is not allowed if the 
          wheel byte is off.  Screen paging is turned off automatically.

     F    Send a final form feed to the printer.  Only effective if the L 
          option is active, a form feed will be sent to the printer after 
          the library directory is printed.

OPTIONS (continued)

     O    Output a list of the matching members to a disk file.  This 
          member-list file will have the same name as the library but with 
          a filetype of DIR.  The order of the member names in the file is 
          determined by the sort mode (option A above).  The file is 
          written to the currently logged directory, but LD may be 
          configured to instead write the file to the directory containing 
          the library.

All options can be configured as defaults (see CONFIGURATION, below).  In 
that case, the command line option will toggle to the non-default mode.
:D

                              DISPLAY DETAILS 

The top line gives the drive, user, and name of the library file, with 
attribute characters in lower-case and highlighted.  The date and time the 
library was created and last modified will also be shown, if they are 
available in the library directory.

There are two types of display screens.  Both displays show the names of 
matching member files and their sizes in records (sectors) and in 
kilobytes, including fractional parts of a kilobyte (.00, .12, .25, .37, 
.50, .62, .75, or .87, indicating 0 to 7 additional records).

The DEFAULT DISPLAY, which shows only one member file per line, includes 
the method by which the file was compressed as "CR" for GEL (LZW) crunched, 
"LZH" for LZH crunched, and "SQ" for squeezed.  Dashes means either the 
file is not compressed or it is compressed by an unrecognized method.

DISPLAY DETAILS (continued)

The default display also shows, if possible, the date and time each member 
file was created and last modified.  If no date and time are found in the 
library directory, crunched files are checked for embedded datestamps.  If 
found, they are displayed instead, with a "~" between the date and time to 
indicate their source.

Finally, the default display gives the real name of crunched and squeezed 
files--the name the file will have when it is uncompressed.

If the C command line option is given with the default display and if a 
crunched file contains an embedded comment, the comment will be displayed 
on a separate line just below the entry for that member, up to 76 
characters with video highlighting, usually surrounded with brackets.  If 
the comment has to be truncated because it is too long, there will be no 
closing bracket.  (It should be noted, however, that occasionally an 
embedded comment may not be terminated in the file header with a closing 
bracket.)

DISPLAY DETAILS (continued)

The ALTERNATE DISPLAY, which shows two member files per line, includes each 
file's cyclic redundancy checksum (CRC) and its index (position offset) 
within the library.  Embedded comments cannot be shown with the alternate 
display; however, more member files fit on the screen and it works faster 
because individual member files are not accessed.

With both displays a final summary line gives the number of matching member 
files found, the number of active members in the library, the number of 
deleted members, the number of free directory entries, and the total 
directory entries.

LD can be aborted anytime with ^K, K, ^X, X, ^C, or C.  Except at the 
"[more]" prompt, a ^S will pause the display until another key is pressed.  
Pressing the space bar at any time sets LD to "line by line" advance 
(unless paging has been turned off with the P option).
:S

                                 SECURITY 

Complete security is assured under ZCPR3 by using the filespec as parsed by 
the command processor.  As additional security, LBR files with the system 
attribute set will be ignored if the wheel byte is off.

For non-wheels, the summary line shows only the number of matching members 
and the number of active member files.

Non-wheels cannot access the command line options "L" and "F" for printer 
output or option "O" for file output, nor are these options shown on the 
usage screen if the wheel byte is off.  If the options are used on the 
command line, no error message is given, but neither the printer nor the 
disk is accessed.  The "M" option for message register output and the "Q" 
quiet mode option are not listed on the usage screen if the wheel byte is 
off, but they can still be used.

For Non-ZCPR3 systems, a wheel-byte address can be configured into the 
program (see configuration) and only the current user area can be accessed.
:E

                                  ERRORS 

On error the ZCPR3 program error flag is set as follows:

    255   no matching member files found
     19   invalid option
     12   insufficient memory (TPA overflow)
     11   disk or directory full (with O option)
     10   library file not found
      4   library is corrupt, no message buffer (with M option), or file 
          close error (with O option)
      2   invalid directory

The error handler, if one is running, will be invoked for all errors, 
except when no matching member files are found (code 255).
:C

                               CONFIGURATION 

Although a large number of configuration options are available, LD should 
be ready to use "as is" for remote access systems (RAS) or individuals 
under ZCPR3.  CP/M users should change the configured number of screen 
lines if their screen has more or less than 24 lines.  Sysops for non-ZCPR3 
remote systems should also install the address of their system's wheel 
byte.

Configuration changes are made with ZCNFG and the accompanying LDnn.CFG 
file.  If the name of the configuration file is not changed, ZCNFG will 
always be able to find it, even if the name of LD is changed to something 
else, such as LDIR.  Full explanations for the various configuration 
options are available on the ZCNFG help screens.

All command line options are toggles and can be configured as the defaults. 
The command line options may then be used to toggle to whatever is the non- 
default state.

CONFIGURATION (continued)

The date displays can be configured for either "American" (mm/dd/yy) or 
"European" (dd.mm.yy) format.  The time displays can be configured for 
either "Civilian" (12-hour time, e.g., "3:21p") or "Military" (24-hour 
time, e.g., "15:21") format.  As distributed, American date and military 
time are used.

With the "M" option the number of matching member files is placed in 
registers 18 and 19 (low byte first), the number of free (unused) library 
directory entries in registers 20 and 21.  The registers used may also be 
changed.
:H

                                  HISTORY 

The starting point for this program was LDIR-B Version 2.2, which gives an 
UNARC-type display of library directories.  Originally written by Steven 
Greenberg, it is the result of several years of continuing development by 
Bruce Morgen, Michal Carson, Sean Sullivan, Howard Goldstein, and Gene 
Pizzetta.  LD will be moving in a slightly different direction, hence, the 
name change.  The goal is to keep this program under 6K (it used to be 4K, 
but Bruce trampled all over that!), about three-times the size of LDIR-B, 
and to provide a more versatile library directory tool with numerous 
command line and configuration options, and making more extensive use of Z- 
System facilities, while remaining compatible with vanilla CP/M.

Version 1.4 -- March 21, 1992 -- Gene Pizzetta
     Bruce Morgen reported a small cosmetic problem on some terminals: With 
     a two-character user number, some terminals were feeding an extra 
     line.  I have pretty much followed Bruce's suggested fix.  A couple of 
     other minor changes cut program size by a whopping five bytes.  The 
     documentation and history files have been replaced with a help file.

Version 1.3 -- February 7, 1992 -- Gene Pizzetta
     Includes all Bruce Morgen's fine additions.  Now uses ZSLIB file-list 
     routines at a considerable saving in size.  As a side-effect, the 
     SYSLIB detailed file error codes are no longer reported.  The 
     destination for the output file is now configurable (default directory 
     or library's directory).  The check for Z-System is now more rigorous, 
     using a method suggested by Jay Sage.  If ZCPR3 is not found, LD now 
     assures that ENVPTR is set to 0 so other routines can detect that no 
     environment exists.

Version 1.2 -- November 6, 1991 -- Bruce Morgen
     Fixed form-feed bug when help screen is invoked, gave screen paging 
     some overlap for readability by using ENV's "usable lines" value (e.g. 
     22) instead of "total lines" (24) and added two new options that I 
     find useful: the LBR directory is now optionally sorted and an ASCII 
     member list is now optionally sent to the file "lbrname.DIR" in the 
     default directory.  The cost of these is the complete demolition of 
     Gene's proposed 4K limit on LD's file size.  The file output feature 
     introduces a number of new error numbers, all of which are derived 
     from the return codes of SYSLIB's byte-oriented file I/O routines with 
     the sole alteration of setting the high bits to distinguish them from 
     previously defined errors:
          129  =  Attempt to write to unopened lbrname.DIR file
          131  =  DOS somehow lost track of lbrname.DIR file
          132  =  Attempted read past EOF (should not happen)
          134  =  Could not close lbrname.DIR file
          135  =  Re-open of lbrname.DIR (should not happen)

Version 1.1 -- October 25, 1991 -- Gene Pizzetta
     Many changes.  Added alternate display of member names, sizes, CRC's, 
     and indexes in two-columns.  Changed some options, added others.  
     Option S prints only the summary line.  Option Q is a true quiet mode. 
     Option M stores the number of matching members and free library 
     directory entries to message registers.  Option D checks for embedded 
     dates in crunched files before checking library directory for dates.  
     Restored configurable wheel byte address for non-ZCPR3 systems.  If 
     wheel is off, now shows number of matching and active members and 
     suppresses display of M and Q (along with L and F) options on usage 
     screen, although M and Q will still work.  In quiet mode output can be 
     sent to the printer.  Top of memory calculation is now less 
     conservative for low memory applications.  Fixed a few bugs, including 
     one that kept LD from running under vanilla CP/M.  Now invokes error 
     handler for errors other than no matching member files found.  A 
     bouquet to Howard Goldstein for his testing and suggestions, which 
     have made this a much better utility.

Version 1.0 -- October 7, 1991 -- Gene Pizzetta
     Added command line options (C, Q, P, L, and F).  Now checks for modify 
     date even if there is no create date.  Displays date in American or 
     European format.  Displays time in military or civilian format.  
     Single-line display of the first 18 bytes of embedded comments 
     abandoned in favor of always displaying the uncrunched or unsqueezed 
     filename.  Embedded comments are now displayed on a separate line (up 
     to 76 characters) in response to a command line option.  Relocatable 
     code uses a large number of library routines.  Wheel security prevents 
     non-wheels from using options L and F or from accessing system files.

For the history of the predecessor program, see LDIR22.LBR.
:B

                        BUG REPORTS AND SUGGESTIONS 

Please report any bugs as soon as possible, and make suggestions at your 
leisure:

                  Gene Pizzetta
                  481 Revere St.
                  Revere, MA 02151

                  Voice:  (617) 284-0891
                  Newton Centre Z-Node:  (617) 965-7259
                  Ladera Z-Node Central:  (213) 670-9465
