Contents of the README file
FARSTR: The automatic far string generator
This is your dilemma:
"I have a very large program which I must compile in LARGE model, because I
have to link large model libraries, yet I am getting DGROUP EXCEEDS 64K
error messages, because I have so many static strings. What can I do?"
This program may be your solution.
FARSTR parses a .C/.CPP file, removes anything within double quotes (within
parentheses or in a 'cout' statement), replaces it with a variable name
(modulenameFarStrxx, where xx is some number), and puts the original string
within comments. A header file with the .FSH extension is created, which
holds the original text now declared as far strings. For safety's sake, the
original .C or .CPP file is not destroyed; instead a new .FS file is created,
which you should be able to copy into a file with a .C/.CPP extension and
compile, with the burden of your static strings taken out of DGROUP.
For power users:
Note that far segment naming is used to force all far items into a common far
data segment; otherwise the 'far' keyword would create a new segment for each
far item. This is done with the #pragma option -zEmodulename_FARSEG at the
top of the .FSH file. Ordinarily this shouldn't cause problems unless you
have done your own far segment naming; in that case, take out whichever far
segment naming comes second. The far segment naming will also prevent you
from having multiple automatic far segments for any single module. This will
limit you to 64K of far data per module; if you have more, then put some large
data items in a separate .C module.
Q: Why do I need this program?
A: Static strings always go into DGROUP in large model, even if you have
automatic far data set. The only way to take them out of DGROUP is to
have separate string (character array) variables declared as far.
Recompiling in huge model would usually take care of this, since each
module has its own data segment, but third-party libraries are often
available only in large model.
Q: Will FARSTR handle such constructs as '"' and \", or nested comments?
Q: I'm getting all these error messages, "Undefined symbol 'xxxFarStrxx'".
A: FARSTR assumes that if the .FSH file already exists in the current
directory, you have run FARSTR on this module before, and so it doesn't
append '#include "xxxx.fsh"' onto the beginning of the new .FS file.
Just #include the .FSH file in your source, and you should be fine.
Q: In the comments which are supposed to hold the original string, I
see things like 'Ce' or 'Cb' or 'CC', which I'm sure I didn't have
in the original string. What's going on?
A: The original string had characters in it which would be interpreted as
beginning or ending a comment. We can't very well keep those characters
within our own comments holding your string; therefore, '/*' has been
replaced with 'Cb' (comment begin), '*/' has been replaced with 'Ce'
(comment end) and '//' has been replaced with 'CC' (double comment).
Q: I ran FARSTR, and then of course I modified the program and included some
more static strings. What should I do?
A: You can safely run FARSTR again to make those strings far also. If you
take out some statements that had been using far strings, FARSTR won't
realize that parts of the .FSH file are no longer needed; you should take
the corresponding strings out of the .FSH header file yourself if you want
to save the space.
Q: I ran FARSTR, and now I'm getting the message "Linker Table Limit Exceeded",
or the compiler runs out of memory or crashes.
A: Check to make sure that #pragma option -zEmodulename_FARSEG
is at the beginning of each .FSH module, before the #include's, to put
these far strings into segment named xxxxx.
Q: I ran FARSTR on my file, and now it no longer compiles!
A: Woops. Send me CompuServe mail at 76701,46 (Richard Wesson)
* No effort is made to match or merge duplicate strings.
* At present, FARSTR makes the assumption that you'll be keeping your header
files and source files in the same directory. Please run FARSTR from the
same directory as the source file it will be working on.
* Don't use FARSTR except with large-model or compact-model programs.
* Please try to take a quick look at the .FS file before copying it into
your .C file, to make sure that it has done what you want.
* Don't modify the .FSH file carelessly; FARSTR figures out how to number
its far string variables from the numbers that it finds in there.
* If the module cannot compile without errors before FARSTR is run on it,
we won't be surprised if FARSTR produces very bizarre results.
* FARSTR may not be very useful in .CPP files because for safety's sake
it refuses to deal with static strings not enclosed by parentheses,
avoiding an erroneous substitution like, "char b=myfileFarString90;"
* We believe this program works as stated; however Borland cannot take
responsibility for any losses that may occur as a result of its use
-- Bugfix 1/22/93: Parentheses within strings that were not themselves in
parentheses could cause strange failures. Example:
char *b= "("; char *a= "Hello";
would generate a far string something like ;char *a=
It shouldn't do this any more.
Also, cout << "Somestring"; will make Somestring into a far string now.