ftp.wwiv.com/ftp.wwiv.com.zip/ftp.wwiv.com/pub/UTILITY/ASR132A.ARJ/ASR.DOC

Text File | 1992-04-09 | 14KB | 289 lines

----------------------------------------------------------------

                        ASR version 1.32
                       March/April,  1992
                    Written by Preston Brown
             #3 @9987 WWIVnet, #2 @9191 VirtualNET

----------------------------------------------------------------

I. What is DGROUP, and ESM?

     ASR stands for AUTOMATIC STRINGS REMOVER.  It was developed
over a period of time to deal with a problem that surfaced in WWIV
4.11/4.12, and is still a threat in WWIV 4.20.  That problem is the
infamous DGROUP compile error.  DGROUP is the program segment that
contains the text, or "strings" for the program, as well as a few
other things that don't amount to very much memory at all.  Because
WWIV's memory model allows only 64 kilobytes of DGROUP space, if
you start modifying your WWIV source code a lot, you will eventual-
ly have too many strings in the source, and you will run into the
DGROUP compile error in the linking process.

     To many people, this was a stone wall.  Various simplistic
modifications had been released on modnet to deal with this
problem, but all of them were just that: simplistic.  They did not
do a good job, and even with them installed, the DGROUP error came
back after only a few more modifications.  Thus, most people were
forced to stop modifying their code, or they were forced to cut out
some of their larger mods, like a non-external casino or fancy file
listing system.

     Then along came Tolkien with his program, External Strings
Manager, or ESM.  To many WWIV modifiers, this program was a
literal lifesaver.  The small modification and the accompanying
executable file enabled you to place strings into an external file,
from where they were called by the modified source code.  This
program is EXCELLENT, and though I have only used through version
1.04, I know that there are more current versions about.  They have
more features than are needed for our purposes, but feel free to
obtain them.  I believe that they cost slightly more money than the
earlier releases.

     ESM was excellent, but there was still one small problem
facing many modifiers: it took way too much time to remove the
strings.  The summer of 1991 I can remember printing out each
individual source code file, marking a string number next to each
string, and then loading up the ESM editor to key them in.  Then I
would have to go back into the code, remove the string, and replace
it with a call to "get_string(xxx)" which was the procedure that
looked in the strings file for string "xxx" and read it in.  For
100 strings, this could take at least 2 hours, if I remember
correctly.  However long it took was too long.  I only did it
because I had to do it to keep modifying!  Later, ver. 1.04 of ESM
added the capability for the ESM editor to read in a text file with
a string on each line, and this sped up things considerably, but
the process was still very slow.

     Then WWIV 4.20 came out, and everyone kind of forgot about the
DGROUP compile error if they switched to that version.  Wayne Bell
(author of WWIV) had made some good steps in his new version, one
of them being adding about 4 or so extra kilobytes of room to the
DGROUP area by optimizing his code more efficiently.  However, I
know from experience that the DGROUP threat is still real, because
on my own WWIV BBS, we are less than 1 kilobyte away from hitting
the DGROUP compile error.

     Recently, a mod claiming to give WWIV 4.20 1 meg of DGROUP space
has been released.  This modification is buggy at best, and dangerous
at worst.  It requires a lot of modification to very sensitive
areas of the source code that Wayne may change in his future versions
of WWIV, which he might release more of now that he has a program
that makes all updates a modification.  WWIV 4.21 is supposed to
be released this March.  Also, the 1 meg DGROUP mod is a very
difficult mod, and it does not give you the control over strings that
ESM does.  When wayne himself does some sort of mod like this, we
can forget about ASR and ESM, but that's just it: HE HASN'T.

     So what was I going to do this time?  Do what I did last
summer?  No, No, NO WAY.  I was not going to waste so much time
doing such a paltry task of string removal again.  There had to
be a better way to get around this unfortunate thing.  And there is.

II. ASR and its capabilities

     Enter ASR.  The Automatic Strings Remover works by actually
removing the strings from the source code FOR YOU!!  The most
common string output routines in the WWIV source code for WWIV
4.12/4.20 are "outstr", "pl", and "prt".  These are the ones that
ESM handles most efficiently and easily, so these are the ones that
ASR can remove.  ASR reads in a WWIV source code C++ file, and then
it removes all the strings to an external strings text file for
you.  It replaces the string in the source code file with a call to
the appropriate string in the text file, all automatically!  In
addition to these basic features, you can configure ASR to prompt
you for each string replacement, so you can weed out removal of
such strings like "NN:" and ":" which are frequently encountered
when you are prompting someone in the source code.  With prompting
on, you can choose not to remove these tiny strings.

     You may also turn on commenting in the source files.  If
commenting is on, once the string is removed to the text file and
the call to "get_string" is inserted, the string is also placed in
comment markers ("/*" and "*/") at the end of the line.  This
comment will be ignored upon compile, however, when you are looking
through your source code files, you can tell what each string call
will produce.  I suggest that you leave this important option on at
all times unless you are very nervous about space on your hard
drive, because if you don't then you are likely to forget what a
call to "get_string" actually brings up, and then you will be
forced to check in ESM, which is a time consuming process to say
the least.

     Last of all, you may enable backups of the source files and
string file.  Though I have tested ASR thoroughly, it may make your
conscience feel better if you know that you will have a backup of
your files automatically made before anything is changed.  If
backups are enabled, ASR will make a .BAK from the source code
file, and a .BAK from the strings file as well.  If any .BAK's of
the same name exist from previous work with ASR or even C++, ASR
will write over them.  This backup option will work. However, like
many mod writers urge you, I ask you to back up all your files in
a ZIP or by some other method before undertaking anything as monumen-
tal as string removal.  Your source code files are just too precious
to risk.

III.  How do I use ASR?

     Before you do anything, you MUST install ESM version 1.04 or
later.  ASR is not a stand-alone program: it requires ESM to do
anything useful!  You can probably get ESM from any local Bulletin
board in your area that supports WWIV, or if you can't find it, you
may call my Bulletin Board, SILICON VALLEY.  My number and network
addresses are listed at the end of the documentation.  After you
have installed ESM, and your source code is compiling correctly
with the ESM modification, you are ready to start "de-stringing"
your source code, and ELIMINATING DGROUP!

     ASR is disgustingly simple.  From the DOS command line, simply
type ASR, the name of the source code file to be "de-stringed", and
then the name of the file for the strings to go to.

      e.g. "ASR NEWUSER.C STRINGS.TXT"

     This will remove all the strings of the types mentioned at the
beginning of the documentation from NEWUSER.C to a ESM text file
called STRINGS.TXT.  Since ESM only uses STRINGS.TXT as the file
that it can read in and convert to STRINGS.DAT, this will be the
usual name.  However, if you are only experimenting, or for any
reason you do not want the strings to go to a STRINGS.TXT file, you
of course could type some other name.  Just remember that ESM will
not recognize the file until it has been renamed to STRINGS.TXT.

     ASR run without any command line options will produce a small
help line.  To configure ASR with the options mentioned earlier,
type

          "ASR /CONFIG"

     and answer the simple questions by simply pressing "Y" or "N".
ASR will create a small file called ASR.CFG that contains your
configuration information.

       ASR is smart.  If you have used ASR on previous files, or
you have been manually writing strings to a STRINGS.TXT file, you
can easily put this as the strings file when you start ASR and it
will tack new strings onto the end of the file with no problem!

     After using ASR, make sure that the STRINGS.TXT file is in the
same directory as ESM.EXE, and start up ESM.  Use the option in ESM
called "read in STRINGS.TXT" or something akin to that.  It should
not be hard to find.  ESM will start working, and it will count
through the strings that it is processing.  When it is done, a new
file called STRINGS.DAT will be created in the current directory.
Read up in the ESM documentation on what to do with this file.  Now
you are ready to do some more mods, or even "de-string" some more
WWIV source code files with ASR/ESM!

IV.  How fast is ASR, and is there anything I need to worry about?

     a. ASR is FAST.  I removed all the strings from a heavily
modified NEWUSER.C source code file (70+ strings) in under half a
minute.  Before ASR, that would have taken several hours, with
commenting and all the like.

     b. ASR is SAFE.  However, there are a few things that you
should know about how ASR works.  ASR looks through your source
code files, and looks for calls to "pl", "prt", and "outstr".
These are the straightforward, everyday string calls.  ASR will not
mess with other types of string calls, such as ones that contain
variables ("%s" and the like) in the string, because ESM cannot
handle such strings.  If it finds such a string, it first makes
sure that it has already been converted to a call to "get_string"
or not.  Here comes my warning: DO NOT, I repeat DO NOT run ASR on
a source code file with invalid code in it.  Make sure that the
code compiles before running it through ASR.  This is because if
you have something like this:

     pl("this is a string where I forgot to put on the end quote.);

     ASR will keep going until it finds a closing quote.  This code
will not compile without an error, and therefore you don't really
have to worry about that ever happening.  If you did run it through
ASR, you would probably end up with some very strange strings being
removed!

     c. ASR can only remove one string per line of code.  Therefore,
if you have a line of code like this for some odd reason:

     prt("this is kinda"); prt("weird!");

    It will compile fine because it is valid code.  However, if you
only run this through ASR one time, it will only catch the first
string, "this is kinda".  it won't mess with the second one.

     If you want to be sure that ASR is doing everything right,
turn on prompting for string removal.  This obviously takes more
time since you have to say yes or no to each question, but if it
gives you a sense of security, do it.  You will probably see soon
that you feel comfortable with it turned off, and you will love the
speed at which it goes through your files.

     d. No program is perfect.  I have tested ASR on all the WWIV
source files and it WORKS.  however, I cannot foresee all the mods
that you or others may stick into the code.  Therefore, unless you
are absolutely sure that everything will be easy for ASR to
interpret, turn on backups, or make your own.

        DISCLAIMER:  I hold no responsibility if ASR trashes your
        files and you didn't make backups because you were
        just plain STUPID.

V. How is ASR distributed, supported, and is it FREE?

     ASR is FREE.  I know that if I ask people to send me money,
more than likely they will send me nothing.  I know how it
works...I have not registered many shareware programs, I admit.  I
register the ones that I love and use very often.  But, if out of
the kindness of your heart, you wish to send me any small token of
thanks for writing ASR, you may send whatever you feel appropriate.
I leave that up to you.

     I DO ask that you mail me and tell me you are using ASR to
"de-string" your code in addition to ESM.  It is so easy for you to
drop me a generic letter saying

     "I love ASR, keep up writing super programs!"

     and then I can count you on my list of users who use my
programs.  I will mail you personally through WWIVnet with any
future product announcements.  This is kind of like "registration":
if you mail me, you can only get more.  If you don't, you might
never learn about some of my stuff.

     You can reach me through one of these Network Addresses:

     #3 (Ellrond) @9987 (Silicon Valley WWIVnet)
     #2 (Ellrond) @9191 (Silicon Valley VirtualNET)

     or just call Silicon Valley.  And here, I shamelessly plug our
BBS system.

     Silicon Valley
     9987 WWIVnet
     9191 VirtualNET
     FIDOnet and INTERnet are on the way!
     HUGE compilation of WWIV mods and external programs.
     Located in Winston-Salem, NC (group 5 WWIVnet)
     [phone], auto-sysop validation.
     USR Dual STD. modem, v.32bis/v.42bis.

   If you wish not to make a long distance call, or you do not have
access to WWIVnet (god forbid!) you can send surface mail to:

                    Preston Brown
                    1110 Arbor Rd.
                    Winston-Salem, NC 27104
                              or
                    Preston Brown
                    Deerfield Academy
                    Deerfield, MA 01342

     If you do send surface mail, I will mail you back a list of
all my current software, and if you enclose $5, I will send you a
disk with all my current software as well as a list.

see UPDATE32.DOC for revision history.

EOF