.=========================================. | | | SUBGEN - The .SUB file Generator | | | | By Steve Pritchard | | Solutions Canada Inc. | | 83 Cummer Ave, | | Willowdale, Ontario | | M2M 2E6 | | | | Copyright(1982) Steve Pritchard | | | '=========================================' Version 1.0 February 13, 1982 SUBGENv1.0 - User Documentation Page 1 HISTORY ------- SUBGEN v1.0 was written the weekend of February 13 after realizing that there was no convenient way to perform some similar operation (whether trivial or complex) upon a group of files under CP/M. Sure, FMAP can generate a list of names but it still needs to be attacked by an editor before any useful work can be done with the NAMES.SUB file generated by FMAP. Then again, WORDSTAR is not that good at changing everything in position 1 to $1. And, even if it could, there often needs to be header and trailer records written on the file to establish an operational environment. Finally, the Mississauga SYSOP Jud Newell once remarked that there is no way to 'Delete everything but ....' under CP/M. SUBGEN solves this problem by allowing a NOT option that inverts the file selection criteria at the last moment. Thus to delete all but .COM files on the default disk, one can use SUBGEN in the following way:- SUBGEN *.COM - ;generate SUBGEN.SUB SUBMIT SUBGEN ;submit this to CP/M OPERATION --------- The command with which to invoke SUBGEN is:- SUBGEN [[d:]afn.ft] [options] SUBGEN generates a file call SUBGEN.SUB. It uses the command line to obtain the filename.filetype search mask (afn.ft portion) and also some optional run time parameters such as the "NOT file" invert option. These parameters are used to select the file names off of the specified disk. These selected file names are then sorted into ascending sequence and the user is notified of how many files are selected. At this point a prompt 'Skeleton?' is displayed asking for skeleton line(s) into which the selected file names will be inserted. More than one skeleton line can be given in which case multiple lines are generated for each file name. A null line terminates the skeleton line input phase of the programs operation. Obviously, part of the skeleton can be commands that operate on the file names. Alternatively, SUBMIT parameters can be included at various points within the skeleton if it is necessary to generate a multi-use .SUB file. SUBGENv1.0 - User Documentation Page 2 SUBSTITUTION FORMULA -------------------- During the generation of the .SUB file from the selected file names SUBGEN copies the skeleton line(s) to the output file once for every selected name. During this copying process SUBGEN looks for occurrences of the substitution character. When found, SUBGEN replaces this character with the current filename.filetype. The standard character is the '@' character (which can be easily changed by recompiling SUBGEN.) Special processing is done by SUBGEN if the @ character is preceded or followed by a period. This is to allow for the possibility of doing global operations on filetypes or on systems. The algorithm is most easily explained by use of examples. Assume that the current file name is ABC.COM. Thus:- era @ => era ABC.COM ;simple case first era b:@ => era b:ABC.COM ;another simple case ren @.old=@ => ren ABC.old=ABC.COM ; . suffix causes fn substitution only dir *.@ => dir *.COM ; . prefix causes ft ; substitution only whatfor .@. => whatfor .ABC. ;suffix has priority OPTIONAL EXTRAS --------------- There are currently five optional parameters specified in the FCB2 position on the command line. They are specified in any order but must not be separated by blanks. When specified they invert the default established at compile time. The standard default is all off except for the 'L' option. This may be different for the SUBGEN you are using. P This causes the selected filenames to be written followed by a question mark (?) during the selection process. This occurs after selection and the possible inversion (See '-' below). ie. You have the last say. A CR or Y response selects the file while an N response rejects the file. H This causes a Header? prompt to be written. It is used to write one or more records to the output file before the body of the file is written using the skeleton definitions. No file name substitution takes place on these header records. A null reply terminates the header record writing process. T Similar to the Header option, the trailer option allows one or more records to be written after the body of the file. SUBGENv1.0 - User Documentation Page 3 - This option inverts the selection process. ie. after doing the normal CP/M file matching algorithm, if this option is specified, the match results are reversed. Thus it is possible to create a file of everything but .COM files by searching for *.COM files with this '-' option specified. As mentioned previously, the 'P' optional prompt occurs after this inversion. (Too hard on the head otherwise). L This option is used to control the logging process to the CP/M console during file generation. The standard SUBGEN has this turned on. Specifying this will flip the logging mode. The SUBGEN.SUB file being created is written to the console after substitution if this option is active. EXAMPLES -------- Note:In these examples the UPPER CASE represents user input except where obviously not user input. SG is my abbreviation for SUBGEN and SS is my abbreviation for SUPERSUB. 1. Rename all .BAK files on the default drive to .ASM. A>SG *.BAK Invoke SUBGEN SUBGEN-...... Normal identifier from SUBGEN There are 10 selected files SUBGENs msg Skeleton?REN @.ASM=@ Refer to substitution rules. Skeleton? Null reply ..... SUBGEN would log at this point. ..... A>SS SUBGEN Now do the renames. 2. You are about to undertake the SUBGEN v2 project. Rename all existing SUBGEN10.* components (DOC, REL, COM, SUB and whatever you have forgotton) about to this new name on the B drive. A>SG B:SUBGEN10.* Invoke SUBGEN SUBGEN-...... Normal identifier from SUBGEN There are 7 selected files SUBGENs msg Skeleton?REN B:SUBGEN20.*=@ Make use of substitution rules Skeleton? Null reply .... SUBGEN would log at this point. .... A>SS SUBGEN Now do the rename SUBGENv1.0 - User Documentation Page 4 3. List all PLI programs on drive B in upper case on your list device with tab expansion every 4 columns. Every program is to start on a new page. You have a file called PAGESEP that you want listed before every program. You also have slow disk drives and want to avoid reloading PIP every time. A>SG B:*.PLI H Invoke SUBGEN with H option SUBGEN-...... Normal identifier from SUBGEN There are 22 selected files SUBGENs msg Header?XSUB Invoke XSUB for PIP Header?PIP then invoke PIP Header? Null reply Skeleton?LST:=B:PAGESEP[P60] Generate page separator command Skeleton?LST:=B:@[T4P60U] Generate PIP commands Skeleton? Null reply .... SUBGEN would log at this point. .... A>SS SUBGEN Now do the lists 4. Compile all PLI programs on drive B, run PGMLINK.SUB and have supper while this is happening. A>SG B:*.PLI T Invoke SUBGEN with T option SUBGEN-...... Normal identifier from SUBGEN There are 33 selected files SUBGENs msg Skeleton?PLI b:@ Generate compile command Skeleton? Null reply Trailer?SS PGMLINK SUPERSUB allows SUBs within SUBs. Trailer? Null reply A>SS SUBGEN Now go have supper. 5. You have to ERA all but your .COM files on the default drive. You wish to confirm each deletion. A>SG *.COM -P Invoke SUBGEN with P and - option SUBGEN-...... Normal identifier from SUBGEN mast.cat?N SUBGEN prompt - reject reply mast.bak? CR means Y too. .... etc There are 2 selected files SUBGENs msg Skeleton?ERA @ Generate the command Skeleton? Null reply .... SUBGEN would log at this point. .... A>SS SUBGEN Invoke the command. 6. Since SUBGEN uses the Read Command Buffer CP/M function it can be driven by XSUB. Therefore, if the right situation came along, a .SUB file could be used to generate a .SUB file by means of SUBGEN. I will leave it to the user to find the right situation where this would be useful. SUBGENv1.0 - User Documentation Page 5 HELP ---- SUBGEN weighs in under the desirable 2k mark and so I was able to imbed a terse but reminding HELP function. It is invoked by typing:- SG ? I hope that this is obvious enough for somebody to try who does not have this documentation package to tell them how to get HELP. DISTRIBUTION ------------ As mentioned in the program listing, this package is placed into the public domain with the usual conditions - Feel free to distribute but it is not to be sold for profit. On my part it represents another small installment to the debt I feel I have amassed in picking up so much good quality software in the public domain. y software in the public domain.