.;- DK:DIRUSR.RNO DATE: 8-SEP-83 TIME: 19:32:56 .ps 58,78;.lm 4;.RM 74;.uc;.ap .t ####TECO BULK DIRECTORY PACKAGE .st ####USER MANUAL REV 8-SEP-83 .C;USER 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 The discussion below refers to the user's view of the multi-volume directory package. For a description of program structure, register use, etc., one should refer to file DIRPGM. Editing functions supported by the VEGB screen macro are identical with those built into the distributed VT52.TEC screen macro. Users are directed to its documentation for information about screen editing. The distributed version is designed for use with a VT52 terminal. It may be run with a VT100 set to VT52 compatibility. Adaptation of the code to make use of VT100 control functions is possible, but requires substantial modification of the VT52 screen macro. For the directory routines, adaptation to VT100 requires only minor changes in the cursor positioning, line erase, and screen erase control sequences. These can all be found by a search for _^A, which will locate character strings that will be sent to the terminal during prompting sequences. .s 2;.c;======##INVOCATION OF FUNCTIONS##====== .s;.LM 12;.TS 12;.I -8 START-UP .s;.i -4 1 Install the following files on the system volume: TECO.SAV (V36), VEGB.TEC, MAKE.TEC, UPDATE.TEC, FIND.TEC, RDIR.TEC, WROUT.TEC, SRCH.TEC, and MERGE.TEC. .s;.i -4 2 Assign logical device name DK: to DX1: (or DY1: for RX02 drives). Under the FB and XM monitors, disable automatic line-wrap with SET TT NOCRLF. Under all monitors, turn off hold-screen mode with SET TT NOHOLD. Leaving hold-screen mode enabled will not cause any malfunctions, but it may lead to confusion when the screen freezes up at unexpected moments. .s;.i -4 3 Start TECO and install the screen support macro with TECO/EXEC#SY:VEGB. TECO will suggest a file name, and request approval or modification. Standard editing keys are available; approves the displayed file specification. Because the directory functions differ considerably from normal editing jobs, all directory functions will ignore any file spec entered at this time. Some disk access may be avoided if the file spec suggested by TECO is accepted without change. On acceptance of the file spec TECO will start the screen macro. If the file spec refers to an existing file, the front of that file will be displayed. .s 2;.i -8 MAKE NEW BULK DIRECTORY .s;.I -4 1 Dismiss the screen macro with a single _^C. The TECO prompting star will appear at the bottom of the screen. Then issue the command EISY:MAKE$$. MAKE will request approval to discard existing text, an open output file, and/or an open input file. On each approval request, a single keystroke of will grant permission to proceed. Any other keystroke will abort MAKE, and control will be returned to the state before invocation of MAKE, with the screen macro re-enabled. .s;.i -4 2 If no risk of data loss was found by MAKE, or if explicit approval was granted to discard text and/or files, MAKE will display a prompting screen directing the user to mount the output volume for the directory file, and to specify the name of that file. If a name of that file already exists, TECO will present a transient warning that the operation will replace an existing file. A length specification may be given with the file name. If no length is specified, MAKE will request the largest available space on the output volume. MAKE then displays a small menu defining two keystroke sequences: ESC V will read directory information from a volume (mounted on DK:), and ESC W will write accumulated directory text onto the output volume. The menu will remain on the screen until the next keystroke. That keystroke is discarded, the screen is cleared, and the screen macro is enabled. .s;.i -4 3 From within the screen macro, a keystroke sequence of ESC V will read directory information from the volume currently mounted on DK: into the text buffer. The screen macro will present that text on the screen for commenting. Neither the volume ID record (line 1), nor any of the file names should be edited; that would defeat the utility of the directory file. The space next to each file name may be filled with comment in free-form format, but no additional CRLF codes should be inserted into the text. .s;.i -4 4 After any desired comments have been entered, a new input volume may be inserted, so that its ID and directory can be read in with a new ESC V command. Whenever the accumulated directory text exceeds 4096 characters, a prompting message will appear at the top of the screen, directing the user to mount the output volume and to signal its presence by striking . No other keys are accepted at this stage. If the wrong volume is mounted, a warning will be displayed, and the user will again be directed to mount the ouput volume. .s;.i -4 5 After output has been written to disk, a message will appear on the top of the screen, offering a choice between closing the output file#(C), or accepting more input volumes#(Y). Depending on the choice made, the user will be informed that the file has been closed, or will be directed to mount the next input volume. .s;.i -4 6 The user has direct control over the writing of output and subsequent closing of the directory file. At any time, a keystroke sequence of ESC W will invoke the output module, independent of the amount of text currently held in memory. From there, the user will be prompted as described above, to mount the output volume, and to choose between collecting further input or closing the output file. .s 2;.i -8 UPDATING AN EXISTING DIRECTORY FILE .s;.i -4 1 Start TECO as described earlier. Then disable screen mode with _^C, and issue a command EISY:UPDATE$$. UPDATE will test the presence of text, input, and output files, and will request approval to discard as needed. A keystroke of indicates approval; any other keystroke will cause UPDATE to abort. On abort, control will be returned to the screen macro. No data or files will have been discarded except those for which approval had been given. .s;.i -4 2 After approval has been obtained to discard text and/or files, UPDATE will write a prompting screen directing the user to mount the output volume on device DK:, and to specify a file name. A length may be specified with the file name. If no length is given, UPDATE will request the largest available space on the output volume. Standard editing functions may be used during entry of the file name. UPDATE verifies presence of the specified file, and issues a warning if that file cannot be found. After the warning, the user may elect to resubmit#(Y) a file name, or to abort#(Q) the operation. If an abort command is given, control is returned to the screen macro, which will then display an empty text buffer. .s;.i -4 3 On acceptance of a file name for an existing file, UPDATE writes a simple menu defining ESC V as the command to read a new directory, and ESC W to merge accumulated updating text with the previously specified directory file. Directory read commands may be given until the accumulated directory text grows beyond 4096 characters. At that time, a prompting message will be written at the top of the screen, directing the user to mount the output volume, and to approve continuation by typing . .s;.i -4 4 Accumulated directory text may be merged with the directory file under user control with the command ESC W, if the update text will not grow to 4096 characters. Independent of the entry path to the merge operation, only a single merge is performed for each update sequence. During the merge, only those pages in the directory file are affected for which an updated volume directory was made. The update volumes may be submitted in random order, and may include volumes for which no entries exist in the current directory file. .s;.i -4 5 The merge operation will remove file entries for which no duplicate was found in the update text, and will remove the new entries for all those files for which a duplicate entry was found in the original directory file. If the merge does not insert any entries in the directory file, the new directory file will be closed, and a message will be displayed stating that revision has been completed. If the merge did entail modifications or additions to the directory file, all modified pages will be placed in the text buffer, and the user will be invited to add comments as needed. On completion of any desired commenting, the directory file must be closed with any of the TECO file-closing commands, e.g. EC, EX, HPEF, etc. These commands may be given either from the screen macro (with the 'RED' key), or directly to TECO after disabling of the screen macro with _^C. .s 2;.i -8 FINDING FILES AND CLASSES OF FILES .S;.I -4 1 Start TECO as described earlier. Then disable screen mode with _^C, and issue a command EISY:FIND$$. FIND will test the presence of text and/or an input file, and will request approval to discard data as needed. A keystroke of will grant approval; any other response will cause FIND to abort, with return to the screen macro. .s;.i -4 2 After obtaining approval to discard data and/or files, FIND presents a prompting screen directing the user to mount the directory volume and to enter the name of the directory file. The presence of that file is verified; if the file cannot be found, a warning will be written, and the user will have the option to resubmit#(Y) a file name, or to abort#(Q) the operation. On abort, FIND will return control to the screen macro. .s;.i -4 3 After the directory file has been satisfatorily defined, FIND will write a small menu indicating that searches may be initiated with a command ESC W. The message disappears on receipt of the next keystroke; that keystroke is discarded, and the screen macro is re-enabled. .s;.i -4 4 From the screen macro, searches may now be initiated. On receipt of the ESC W command, the search routine will write a prompting screen defining allowed wildcard constructions, and requesting entry of a search string. In that string, may be used as a wildcard for the character group A-Z and 0-9. The symbol <*> may be used as a wildcard for A-Z, 0-9, and . Thus a pattern ABC? will match all four-character file names starting with ABC, and ABC?* will match all four- and five-character file names starting with ABC. The search pattern is explicitly taylored to search for file names: a single <.> may be present, but not more than six characters may precede it, nor can there be more than three characters after the period. Search patterns that do not meet these requirements will be rejected with an explanatory warning, after which the user may submit a new search pattern. .s;.i -4 5 After acceptance of a search pattern, the directory file is opened and scanned for occurrances of the pattern. During the search, a message is displayed at the top of the screen. On completion of the search, all matching entries found will be written to the text buffer for inspection. Entries are grouped by storage volume, with the ID of each volume as the first record in each group. Groups are separated by blank records. .s;.i -4 6 The results of the search may be inspected with the help of the screen macro, or the text may be written to a file or to a printer by means of standard TECO output commands. For example, EWLP:$HPEF$$ will write the content of the text buffer to the line printer. .s 2;.lm 4 .c;OTHER APPLICATIONS UPDATE lends itself well to the maintenance of a README files for single volumes. The README file must be created by MAKE, with the same volume serving for both input and output. After that, each modification of the file content of the volume can be inserted easily into the README file with UPDATE, again without any volume swapping. .s 3;.c;GENERATED MESSAGES .S 2;.lm 4;.RM 78;.nf;.nj;.sp 2 -MAKE-W- TEXT IN BUFFER - OK to discard? (Y) -MAKE-W- OUTPUT FILE OPEN - OK to discard? (Y) -MAKE-W- INPUT FILE OPEN - OK to discard? (Y) -MAKE-I- NO OUTPUT FILE SUPPLIED - STRIKE ANY KEY TO EXIT .sp 1 -MAKE-M- ESC V (PF4) READS NEW VOLUME - ESC W (PF5) WRITES OUTPUT - --- strike any key to remove this message and proceed ---- .S;.sp 2 -MAKE-W- WRONG VOLUME - PLEASE CORRECT - OK to proceed? (Y) -MAKE-I- WRITING TO OUTPUT VOLUME - -MAKE-P- MORE INPUT (I) or CLOSE OUTPUT (C) ? -MAKE-I- OUTPUT CLOSED - TYPE ANY KEY TO EXIT FROM -MAKE- -MAKE-P- MOUNT NEXT INPUT VOLUME - OK to proceed (Y) ? -UPDATE-W- TEXT IN BUFFER - OK to discard? (Y) -UPDATE-W- OUTPUT FILE OPEN - OK to discard? (Y) -UPDATE-W- INPUT FILE OPEN - OK to discard? (Y) -UPDATE-I- NO FILE NAME SUPPLIED - STRIKE ANY KEY TO EXIT -UPDATE-W- file.ext DOES NOT EXIST - RE-ENTER (Y) or QUIT (Q) ? .sp 1 -UPDATE-M- ESC V (PF4) READS NEW VOLUME - ESC W (PF5) MERGES OUTPUT - ---- POSTPONE INSERTION OF COMMENTS UNTIL MERGE STAGE ---- ---- strike any key to remove this message and proceed ---- .S;.sp 2 -UPDATE-P- INSERT DIRECTORY VOLUME - OK to proceed? (Y) -UPDATE-W- WRONG VOLUME - PLEASE CORRECT - OK to proceed? (Y) -UPDATE-I- UPDATING DIRECTORY FILE - -UPDATE-I- REVISION COMPLETED - strike any key to exit - -UPDATE-P- COMMENT TO TASTE, THEN CLOSE FILE WITH HPEF - -FIND-W- TEXT IN BUFFER - OK to discard? (Y) -FIND-W- OUTPUT FILE OPEN - OK to discard? (Y) -FIND-W- INPUT FILE OPEN - OK to discard? (Y) -FIND-W- NO FILE NAME SUPPLIED - STRIKE ANY KEY TO EXIT -FIND-W- file.ext DOES NOT EXIST - RE-ENTER (Y) or QUIT (Q) ? -FIND-M- USE ESC W TO SUBMIT SEARCH PATTERN - strike any key to proceed -SRCH-W- TEXT IN BUFFER - OK to discard (Y)? -SRCH-W- NO FILE NAME SUPPLIED - RE-ENTER (Y) or QUIT (Q) ? -SRCH-W- PATTERN TOO LONG - RE-ENTER (Y) or QUIT (Q) ? -SRCH-W- NAME FIELD TOO LONG - RE-ENTER (Y) or QUIT (Q) ? -SRCH-W- TOO MANY <.> - RE-ENTER (Y) or QUIT (Q) ? -SRCH-W- TYPE FIELD TOO LONG - RE-ENTER (Y) or QUIT (Q) ? -SRCH-I- STARTING SEARCH OF file.ext