.;- DK:DIRPGM.RNO DATE: 8-SEP-83 TIME: 19:36:06 .ps 58,74;.lm 4;.uc;.ap .t ####TECO BULK DIRECTORY PACKAGE .st ####PROGRAM NOTES REV 8-SEP-83 .C;PROGRAMMER'S NOTES FOR TECO-BASED MULTI-VOLUME DIRECTORY PACKAGE .S;.C;Copyright 1983 M. van Swaay .S 3 .C;Dr. M. van Swaay .C;Dept. of Computer Science .C;Kansas State University .C;Manhattan, Kansas 66506 .S 3;.c;======##FILES##====== .S;.LIT DIRMV .RNO DECUS paper, St.-Louis May 1983 DIRPGM.RNO This file, as RUNOFF input DIRUSR.RNO User manual, as RUNOFF input MAKE .TEC Creates new multi-volume directory on DK: RDIR .TEC Reads ID and directory, allows commenting WROUT .TEC Writes to output, then close or continue UPDATE.TEC Updates multi-volume directory files MERGE .TEC Does edit/append for UPDATE FIND .TEC Accepts directory file spec, installs SRCH SRCH .TEC Accepts search patterns, searches dir. file VEGB .TEC Modified version combining VEG and enhanced VT52, serves as base for other routines .ELI .S;.C;======##GENERAL OBSERVATIONS##====== Prompting texts in these files contain sequences of <#ESC#p#> and <#ESC#q#> to control inverse video on Z19 terminals. Those terminals may not be as common as the VT52 and VT100 series, but it is much easier to remove the sequences from where they occur, than to insert them where they should be. To remove them, edit all .TEC files except VEGB with the command: J<:@S/$p/;-2D>J<:@S/$q/;-2D>$$. If left in place, the inverse video commands will be ignored by VT52 terminals. The package is written explicitly to handle volumes on device DK: only. Supporting *.TEC files must all reside on SY:. There is reason for this rigidity: if mass storage devices other than SY: and DK: are available, their presence removes much of the inconvenience of directory searches across multiple volumes. With SY:, DK:, and one additional mass storage device, directories from multiple volumes on DK: can easily be collected onto a single volume on the third storage device. Directory searches across multiple volumes are cumbersome only on systems with no more than two (small) mass storage devices. .s 2 .c;======##REGISTER INVENTORY##====== .s .c;NO REGISTERS ARE STACKED OR RESTORED .c;OTHER THAN THE SCREEN SET .s;.nf;.ts 12 1 Edit flag for file-spec stage in MAKE A Transient, search pattern used by MERGE for update editing A and by SRCH for directory file searches Anum Pointer used by MERGE during editing B MERGE collects hold-over records here for update pass B SRCH collects search output here Bnum Pointer used by MERGE during editing C Transient storage used by MERGE C SRCH collects single-page output here Cnum Success flag for SRCH D Directory text collector, used by RDIR, WROUT, and MERGE F File spec defining directory file passed by UPDATE to MERGE I Modified VT52 screen support macro O Output Volume ID during MAKE T Transient data, input chars from KB U Inserts missing linefeeds, installed by VEGB V Swaps char. pairs if not margin or ends, installed by VEGB W 24-line up-scroll, installed by VEGB X RDIR: Directory read routine, installed by MAKE and UPDATE Y Transient command early in MAKE Y WROUT, Output and Close routine, installed by MAKE Z Sets image type-out mode and drains KB ring, installed by MAKE and UPDATE, used for all prompting sequences .s 2;.F;.J .c;======##FUNCTIONS:##====== .s;.LM 12;.TS 12;.I -8 MAKE NEW BULK DIRECTORY: .s;.I -8 MAKE MAKE is the start-up file for the directory creation package. It must be invoked as a command file from SY:. In addition to MAKE, files RDIR.TEC and WROUT.TEC must be present on SY: MAKE first installs a routine in Z that will set typeout to image mode, and that will drain the KB ring buffer. This routine is used by all prompting sequences, to avoid accidental fall-through on unread KB input. MAKE then performs three tests: for presence of existing text, for open output file, and for open input file, in that order. If any test indicates potential loss of data, MAKE requests approval to discard before performing the next test. If approval of any data loss situation is withheld, MAKE aborts and returns control to the modified VT52 screen macro. After all tests have been passed, MAKE clears the screen, writes a message including the current revision date of the package, and prompts for insertion of the output volume and specification of the output file name. The output must be written to DK:; the device name is pre-written and cannot be edited at run-time. If no explicit length spec is given with the output file name, MAKE will append a length spec of -1 to claim the largest available space. MAKE then opens the output file, and records the ID on which that file is opened in reg.#O. The recorded ID will be compared against the volume ID on DK: before all write operations to DK:, to guard against accidental overwriting on other volumes. Finally MAKE reads RDIR.TEC and WROUT.TEC from SY:, and installs those routines in regs. X and Y respectively. After RDIR and WROUT have been installed, MAKE writes a small menu in inverse video on the top line. The first keystroke removes the menu and starts the modified VT52 screen macro, from where read and write operations can be invoked with escape sequences. .S;.I -8 RDIR RDIR is invoked from the keyboard with ESC V (PF4 on Z19 terminals). RDIR first appends any text from the workspace onto reg.#D, including a trailing formfeed if the workspace was not empty. RDIR then reads the volume ID and directory from the volume mounted on device DK:, and formats it to align file extensions. Control is then returned to the screen macro, to allow commenting if desired. If RDIR finds more than 8 blocks of text in reg.#D after appending any text from the workspace, RDIR transfers control to WROUT for an output step. This action is announced by a prompt in inverse video on the top line. .S;.I -8 WROUT WROUT performs output and close operations. WROUT begins by testing the workspace, and appending any text found there to reg.#D. Although normally RDIR will leave an empty workspace for WROUT, WROUT can be called manually with ESC W (PF5 on Z19 terminals), to allow wrap-up of a directory file under control from the user. After all text has been collected into reg.#D, WROUT writes a prompt in inverse video on the top line, requesting insertion of the output volume. WROUT will proceed from there only on receipt of a "Y" keystroke. Other keystrokes, with the exception of double ^C, will ring the bell and leave the prompt in place. On approval, WROUT verifies the presence of the proper volume from its ID. If the expected ID is not found, WROUT writes a warning and waits for a "Y" keystroke to proceed. WROUT will only proceed to output activity when it finds the proper ID on device DK:. Next WROUT transfers the content of reg.#D to output and reports that activity on the top line. On completion of the write operation WROUT prompts with a choice between two paths: continue collecting input, or close output file. Only responses of "I" (more input) or "C" (close) are accepted. Any other keystroke will echo as a bell. A response of "I" generates a new message, prompting the user to mount a new input volume. WROUT waits for a response of "Y" and then transfers control to RDIR. On response of "C" WROUT closes the output file, and then prints a confirm message. Any keystroke will remove the message, and will transfer control to the screen macro. To discard unread input left over from the last RDIR acitivity, WROUT attempts to open DK:QQQQQ.QQQ, and in the unlikely event that such a file exists, WROUT then reads to the end of that file. .S 2;.I -8 UPDATE EXISTING MULTI-VOLUME DIRECTORY FILE: .S;.I -8 UPDATE UPDATE is the start-up file for the update package. UPDATE, like MAKE, installs a macro in Z that drains the KB ring, and enables image typeout for prompts. Then UPDATE performs the same set of data loss tests as MAKE. When all tests have been satisfied UPDATE prompts for insertion of the directory volume, and requests a file name. Presence of the file is verified, but access to the file is postponed. The file spec is stored in F for later use. If no explicit length is specified, UPDATE appends a length spec of [-1]. If the specified file is not found, UPDATE prints a warning and allows two paths: RE-ENTER file spec, or QUIT. On QUIT, UPDATE returns control to the screen macro, with an empty workspace. On acceptance of a file spec, UPDATE reads and installs RDIR and MERGE from SY: into registers X and Y respectively. UPDATE then prints a small menu defining ESC V as a read command and ESC W as a merge/edit command. The menu goes away on the first keystroke; that keystroke is then discarded. The update package performs both changes and additions, but will not delete entire volume directories. Directories of new and modified volumes may be read in random order with the ESC V command. Although the newly read directories may be commented as they are read in, it is better to postpone commenting until later for two reasons: the total amount of update space is limited to eight blocks before the merge operation, and the merge operation will retain comments on existing file entries. Directory text is accumulated in reg.#D for later use by MERGE. When collected directory text grows beyond eight blocks, RDIR transfers control to MERGE for insertion and merging with the previously specified directory file. In contrast with the MAKE package, MERGE always closes the directory file after editing. If the updating text covers less than eight blocks, MERGE can be invoked manually with the ESC W command. .S;.I -8 MERGE MERGE begins with verification of the proper output volume. To insure that the proper volume directory is used for access of the directory file, MERGE first opens SY:SWAP.SYS, and then discards that channel. MERGE then opens the specified directory file in backup mode. MERGE next reads through the file page by page, and tests each page against the new directory pages previously created by RDIR and now held in reg.#D. If the volume ID of the current input page is not matched by any of the new directories created earlier, MERGE will pass the current input page to output. If a match is found among the new directories, MERGE will merge the two copies and collect the result into reg.#B. The merge operation will remove old file entries that do not appear in the new copy, and will remove the new entries of all duplicate file names. Thus MERGE will retain commented entries where possible. Directory pages merged in this manner will be collected in reg.#B for subsequent commenting. After the input file has been exhausted MERGE will present all remaining unwritten text for commenting. This text will include new entries in previously existing directory pages, as well as complete directories of newly presented volumes. After all comments have been entered, the new directory file has to be closed by hand with any of the normal TECO closing commands, e.g. EC, PEF, EX, or EG. .s 2;.i -8 SEARCH DIRECTORY FILE, WITH WILDCARD SUPPORT: .s;.i -8 FIND FIND is the start-up routine for search operations in bulk directory files. FIND installs the screen control and KB drain routine in Z, requests approval for data loss situations (text in buffer, open output file, open input file), and then accepts a file spec for the directory file. Presence of the file is verified; then the file spec is stored in F for later use by SRCH. FIND then writes a small menu reminding the user that ESC W will invoke SRCH. The next keystroke will remove the menu and transfer control to the screen macro. The keystroke itself is discarded. .s;.i -8 SRCH SRCH is the routine that performs searches across the directory file specified via FIND. SRCH, like other parts of the package, guards against loss of text in the workspace, and prompts the user for a search pattern. The pattern supports and <*> as wildcards, with allowing any character or digit, and <*> allowing any single character (printing, spacing, or non-printing). The pattern supplied is tested for compatibility with standard filespecs. It may contain 0 or 1 period; the name field must have a length of not more than 6 chars, and the type field, if supplied, must have a length of not more than 3 chars. An empty pattern is refused by SRCH. On acceptance of the search pattern, SRCH opens the directory file and extracts all entries that satisfy the search pattern. The results are collected page by page in C, from where they are transferred and added to B if any hits were found on a given page. On completion of the search, all collected text is brought into the workspace, with blank lines between groups of each disk volume. Control is then returned to the screen macro for display and further disposition. There are no provisions for writing to any output device; that can be handled by the standard TECO commands accessible from the screen macro.