DIRFIRST: (General description and operation.) Z-80 sorted directory showing of first line(s) of files. This file documents version 3.1, written February 28, 1986. Copyright 1986 by Bob Abrahams, released for non-commercial use at no cost. May not be sold. All other rights reserved. Messages for the author can be left on Kim Levitt's Micro-BBS system in Hollywood, CA (213-653-6398) or on Abel Iwaz's Literaria BBS in Glendale, CA (818-956-6164). NOTE: This version is written using Z-80 instructions, so it should be run on Z-80 CPU systems only. This program lists a sorted disk directory (with file sizes) that also shows the first line(s) of each file (if printable). This feature can be used to provide additional information on files beyond the name of the file alone. This is intended primarily for text files, but other file types can be displayed. The user must put the additional description or other information on the first line(s) of the file, with less than 80 characters in each line. The display of each line will stop at any carriage return. If file is to be used by WordStar, the line(s) can be set up as a "comment" line by starting the line with two periods. Any blank lines are skipped, including lines with blanks and tabs only. The contents of some files (those with certain extensions, such as .COM and .OVR) will not be displayed (unless the $A option is used). In any case, in displaying the contents line of the file, control characters are suppressed, and each line stops at the first carriage return or at the end of the first console line* so that "unprintable" files do not wreak havoc even if displayed. * In this version, console width is assumed to be 80 chars. Squeezed files (with file type ?Q?) of the standard type squeezed by the various public domain CP/M squeezing programs are unsqueezed, unless the program is modified as listed below, or unless the original file is of an "unprintable" type. Whether or not the unsqueezing is done, the squeezed and original file names are still listed, even if of an "unprintable" type. The check for file type can be skipped by uising the appropriate options. It is suggested that the user change the name of the program to D1.COM for easier use. D1 is called similar to DIR -- that is, D1 {} {$} As with DIR, the parameter can be any file specification, ambiguous (containing wildcard characters * and/or ?) or unambiguous, including an optional drive specification. Only standard CP/M drive specifications are permitted (e.g. B:). This version is NOT set up to use ZCPR-type drive/user specifications, such as B1:. Options are indicated with a dollar sign ($) followed by the requested option code(s). Spaces may not be embedded between the dollar sign and the option codes. As created, the defaults for most options is OFF. Default for options $L (Libraries) and $X (eXclude types) is ON. See below for information on patching for other defaults. In this version, the options are: A: display contents of All files. (Otherwise supress the display of the contents of files with some types: .COM, .OBJ, .SYS, .OVR, etc.) When listed types are supressed, a squeezed file whose original name is on the "unprintable" list will not be unsqueezed and displayed. S: include SYS attribute files. Normally these files are supressed from the listing. X: eXclude files on the "bad" type list altogether. (Not even listed in the directory.) This does not exclude squeezed files by their original name, though this can be done by including ?Q? to the type table (see patching procedure below), which will exclude all files with type ?Q?, whether truely squeezed or not. Overrides the $A option. Default for this option is ON. L: open Library files (type .LBR), list member names and sizes and display the contents of each member, following the same rules as under option A with regard to files not displayed. (With no $L, option, files with type .LBR are not displayed, unless option A is used.) Library members are shown in order in library directory (sorted only if created by library utility that sorts its directory.) Default for this option is ON. K: show file sizes in 1K increments. Normally file sizes are shown in disk block increments. (This has no real effect if the drive referenced has 1K blocks.) Library member sizes are always shown in 1K increments. N: No paging. Do not stop at the end of each screen.* (May be used with CP/M ^P echo feature to print output on list device.) Normally, the display stops at the end of each screen with the message "More...". The program then waits for any key to be pressed. At this point (or at almost any other point in the execution), pressing ^C will abort the program execution. * In this version, screen height is assumed to be 24 lines. 1-9: List this number of lines from each file. Default is normally 1 line (thus DIRFIRST). With 1 line requested, no page break will occur between the file or member name and the first line of that file. With more than one line selected, a page break may occur in the middle of the file display. (Obviously this does not apply if the $N option is ON and there is no paging.) If more lines are requested than are in the file, an extra blank line may be shown at the end of the display for that file. All options used are listed on the command line together following a dollar sign. For example, to list files on drive B:, opening Libraries, displaying contents of All files, and including SYS files, use the command D1 B: $LAS. Option codes may be listed in any order. Program operation may be aborted at any time by pressing ^C (Control and C keys together.) On some system, this entry is blocked during disk reads. Those with buffered keyboard entries will not have this restriction. ----------------------------------------------------- Making modifications to .COM file (patching): (Use DDT, SID or other file patcher to make modifications.) 1) The list of files that cannot be displayed (except under A option) is located near the beginning of the program, following the sign-on message. This is a table in which each entry has three characters, each representing an unprintable file type. The character following the last entry must be a 00 byte to terminate the scan. The ? character can be used to represent any character (wildcard). (The * wildcard cannot be used.) An entry starting with a period (.xx) may be used to hold a space to be skipped, since there can never be a type starting with a period. 2) Library files (type .LBR) are checked against a string following the above table. This string is 4 bytes long, consisting of the letters LBR and terminating with a 00 byte. If .LBR files are not to be checked as Libraries, then patch out the character L with a 00 byte to terminate the comparison. 3) Immediately following the 00 byte terminating the LBR string above is a table used to check for and set options. Each entry in this table consists of the option letter and a byte used to store the status of the option. A value of zero sets the option off. The last entry is followed by a 00 byte terminator. To set the option default on, set the 0 byte for that option to non- zero. With the default set on, using the option letter in the option group on the command line (following the $) then sets the option off. (Actually, each use of the option represents a toggle. Normally, using any option twice leaves the option off.) 4) Following the above table, is the character "#" followed by a byte with the value 01. This second byte is the default value of the number of lines to be printed. It can be set for any value from 1 to 9. DO NOT SET THIS VALUE TO 00. (It is recommended not to use a value over 9.) 5) The program includes an unsqueezing section which pushes the total size of the .COM file over 2K. If no unsqueezing is to be done (perhaps because no squeezed files are included) and the user wants the file to be within 2K, the unsqueezer can be deactivated and removed. To do this, use DDT or SID as follows: load the program into memory using DDT or SID. If using SID, start with the CP/M command SID D1. Then use the SID command W.COM,0100,08FF, then exit with the SID command G0. If using DDT (on CP/M 2.2), start with the CP/M command DDT D1.COM, then immediately exit DDT with the G0 command, then use the CP/M command SAVE 8 .COM. With CP/M 2.2, use SID or DDT to be sure to SAVE an initialized version of the program. With CP/M 3.0, only use SID, with its W command. In both cases is the new temporary name of the program. It may be renamed to D1.COM after testing. The file D1/NOUSQ.COM has been prepared in this way.