.=========================================.
                 |                                         |
                 |     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
       -------

       SUBGEΠ v1.�� wa� writte� th� weeken� o� Februar�� 1�� afte� �
       realizin� tha� ther� wa� n� convenien� wa�� t� perfor� som� �
       simila� operatio� (whethe� trivia� o� complex� upo� � grou� o� �
       file� unde� CP/M�� Sure� FMA� ca� generat� � lis� o� name� bu� i� �
       stil� need�  t� b� attacke� b� a� edito� befor� an� usefu� wor� �
       ca� b� don� wit� th� NAMES.SU� fil� generate� b� FMAP.

       The� again�� WORDSTA� i� no� tha� goo� a� changin� everythin� i� �
       positio� � t� $1�� And� eve� i� i� could� ther� ofte� need� t� b� �
       heade� an� traile� record� writte� o� th� fil� t� establis� a� �
       operational environment.

       Finally�� th� Mississaug� SYSO� Ju� Newel� onc� remarke� tha� �
       ther� i� n� wa� t� 'Delet� everythin� bu� ....�� unde� CP/M� �
       SUBGE� solve� thi� proble� b� allowin� � NO� optio� tha� invert� �
       th� fil� selectio� criteri� a� th� las� moment�� Thu� t� delet� �
       al� bu� .CO� file� o� th� defaul� disk� on� ca� us� SUBGE� i� th� �
       followin� 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]

       SUBGE� generate� � fil� cal� SUBGEN.SUB� I� use� th� comman� lin� �
       t� obtai� th� filename.filetyp� searc� mas� (afn.f� portion�� an� �
       als� som� optiona� ru� tim� parameter� suc� a� th� "NOԠ file� �
       inver� option��  Thes� parameter� ar� use� t� selec� th� fil� �
       name� of� o�  th� specifie� disk�� Thes� selecte� fil� name� ar� �
       the� sorte� int� ascendin� sequenc� an� th� use� i� notifie� o� �
       ho� man� file� ar� selected��

       A� thi� poin� � promp� 'Skeleton?�� i� displaye� askin� fo� �
       skeleto� line(s�� int� whic� th� selecte� fil� name� wil� b� �
       inserted�� Mor� tha� on� skeleto� lin� ca� b� give� i� whic� cas� �
       multipl� line� ar� generate� fo� eac� fil� name�� �� nul� lin� �
       terminate� th� skeleto� lin� inpu� phas� o� th� program� �
       operation.

       Obviously�� par� o� th� skeleto� ca� b� command� tha� operat� o� �
       th� fil� names�� Alternatively� SUBMI� parameter� ca� b� include� �
       a� variou� point� withi� th� skeleto� i� i� i� necessar�� t� �
       generat� � multi-us� .SU� file.






                    SUBGENv1.0  -  User  Documentation         Page    2


       SUBSTITUTION FORMULA
       --------------------

       Durin� th� generatio� o� th� .SU� fil� fro� th� selecte� fil� �
       name� SUBGE� copie� th� skeleto� line(s� t� th� outpu� fil� onc� �
       fo� ever� selecte� name� Durin� thi� copyin� proces� SUBGE� look� �
       fo� occurrence� o� th� substitutio� character� Whe� found� SUBGE� �
       replace� thi� characte� wit� th� curren� filename.filetype�� Th� �
       standar� characte� i� th� '@� characte� (whic� ca� b� easil� �
       change� b� recompilin� SUBGEN.�

       Specia� processin� i� don� b� SUBGE� i� th� �� characte� i� �
       precede� o� followe� b� � period�� Thi� i� t� allo�� fo� th� �
       possibilit�� o� doin� globa� operation� o� filetype� o� o� �
       systems�� Th� algorith� i� mos� easil� explaine� b�� us� o� �
       examples� Assum� tha� th� curren� fil� nam� i� ABC.COM� Thus:-

       era @         => era ABC.COM            ;simple case first

       era b:@       => era b:ABC.COM          ;another simple case

       re�@.old=�   =� re� ABC.old=ABC.CO�    ; � suffi� cause� f�
                                                  substitution only

       di� *.�  ��   =� di� *.CO�       �     ; � prefi��cause� f�
                                               ;  substitution only

       whatfo� .@��� =� whatfo� .ABC�          ;suffi� ha� priority


       OPTIONAL EXTRAS
       ---------------

       Ther� ar� currentl� fiv� optiona� parameter� specifie� i� th� �
       FCB�� positio� o� th� comman� line�� The� ar� specifie� i� an� �
       orde� bu� mus� no� b� separate� b� blanks�

       Whe� specifie� the� inver� th� defaul� establishe� a� compil� �
       time�� Th� standar� defaul� i� al� of� excep� fo� th� 'L� option� �
       Thi� ma� b� differen� fo� th� SUBGE� yo� ar� using�

       P�   Thi� cause� th� selecte� filename� t� b� writte� followe� b� �
       ������ questio� mar� (?� durin� th� selectio� process�� Thi� �
       �����occur� afte� selectio� an� th� possibl� inversio� (Se� '-� �
       �����below)�� ie�� Yo�� hav� th� las� say�� � C� o� ٠ respons� �
       �����select� th� fil� whil� a� � respons� reject� th� file�

       H    Thi� cause� � Header�� promp� t� b� written�� I� i� use� t� �
       �����writ� on� o� mor� record� t� th� outpu� fil� befor� th� bod� �
       �����o� th� fil� i� writte� usin� th� skeleto� definitions�� N� �
       �����fil� nam� substitutio� take� plac� o� thes� heade� records�  �
       ������ nul� repl� terminate� th� heade� recor� writin� process.

       T    Simila� t� th� Heade� option�� th� traile� optio� allow� on� �
       �����o� mor� record� t� b� writte� afte� th� bod� o� th� file. �


                    SUBGENv1.0  -  User  Documentation         Page    3



       -    Thi� optio� invert� th� selectio� process�� ie�� afte� doin� �
       �����th� norma� CP/� fil� matchin� algorithm�� i� thi� optio� i� �
       �����specified�� th� matc� result� ar� reversed�� Thu� i� i� �
       �����possibl� t� creat� � fil� o� everythin� bu� .CO͠ file� b� �
       �����searchin� fo� *.CO� file� wit� thi� '-� optio� specified� A� �
       �����mentione� previously�� th� 'P� optiona� promp� occur� afte� �
       �����thi� inversion� (To� har� o� th� hea� otherwise).

       L�   Thi� optio� i� use� t� contro� th� loggin� proces� t� th� �
       �����CP/� consol� durin� fil� generation� Th� standar� SUBGE� ha� �
       �����thi� turne� on�� Specifyin� thi� wil� fli� th� loggin� mode� �
       �����Th� SUBGEN.SU� fil� bein� create� i� writte� t� th� consol� �
       �����afte� substitutio� i� thi� optio� i� active.


       EXAMPLES
       --------

       Note:I� thes� example� th� UPPE� CASŠ represent� use� inpu� �
       �����excep� wher� obviousl� no� use� input� S� i� m� abbreviatio� �
       �����fo� SUBGE� an� S� i� m� abbreviatio� fo� 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.   Yo� ar� abou� t� undertak� th� SUBGE� v� project� Renam� al� �
       �����existin� SUBGEN10.� component� (DOC�� REL�� COM�� SU  an� �
       �����whateve� yo� hav� forgotton� abou� t� thi� ne� nam� o� th� � �
       �����drive.

       A>SG B:SUBGEN10.*               Invoke SUBGEN
       SUBGEN-......                   Normal identifier from SUBGEN
       There are 7 selected files      SUBGENs msg
       Skeleton?REΠB:SUBGEN20.*=��    Mak� us� o� substitutio� rule�
       Skeleton?                       Null reply
        ....                           SUBGEN would log at this point.
        ....
       A>SS SUBGEN                     Now do the rename










                    SUBGENv1.0  -  User  Documentation         Page    4


       3.�  Lis� al� PL� program� o� driv� � i� uppe� cas� o� you� lis� �
       �����devic� wit� ta� expansio� ever� � columns�� Ever� progra� i� �
       �����t� star� o� � ne� page�� Yo� hav� � fil� calle� PAGESE� tha� �
       �����yo�� wan� liste� befor� ever� program�� Yo� als� hav� slo� �
       �����dis� drive� an� wan� t� avoi� reloadin� PI� ever� 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.�  Compil� al� PL� program� o� driv� B�� ru� PGMLINK.SU  an� �
       �����hav� suppe� whil� thi� i� happening.

       A>S� B:*.PL� �                  Invok� SUBGE� wit� � option
       SUBGEN-......                   Normal identifier from SUBGEN
       There are 33 selected files     SUBGENs msg
       Skeleton?PLI b:@                Generate compile command
       Skeleton?                       Null reply
       Trailer?SӠ PGMLIN�             SUPERSU� allows SUB� withi� SUBs.
       Trailer?                        Null reply
       A>SS SUBGEN                     Now go have supper.


       5.�  Yo�� hav� t� ER� al� bu� you� .CO� file� o� th� defaul� �
       �����drive� Yo� wis� t� confir� eac� deletion.


       A>S� *.COM -P                   Invok� SUBGE� wit� 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.�  Sinc� SUBGE� use� th� Rea� Comman� Buffe� CP/� functio� i� �
       �����ca� b� drive� b�  XSUB�� Therefore�� i� th� righ� situatio� �
       �����cam� along�� � .SU� fil� coul� b� use� t� generat� � .SU� �
       �����fil� b� mean� o� SUBGEN� � wil� leav� i� t� th� use� t� fin� �
       �����th� righ� situatio� wher� thi� woul� b� useful.




                    SUBGENv1.0  -  User  Documentation         Page    5


       HELP
       ----

       SUBGE� weigh� i� unde� th� desirabl� 2� mar� an� s� � wa� abl� t� �
       imbe� � ters� bu� remindin� HEL� function�� I� i� invoke� b� �
       typing:-

                 SG ?

       ɠ hop� tha� thi� i� obviou� enoug� fo� somebod� t� tr� wh� doe� �
       not have this documentation package to tell them how to get HELP.


       DISTRIBUTION
       ------------

       A� mentione� i� th� progra� listing�� thi� packag� i� place� int� �
       th� publi� domai� wit� th� usua� conditions - Fee� fre� t� �
       distribute but it is not to be sold for profit.

       O� m� par� i� represent� anothe� smal� installmen� t� th� deb� � �
       fee� � hav� amasse� i� pickin� u� s� muc� goo� qualit�� softwar� �
       in the public domain.