The "Symbols=filename" option on a BOFF command line is used to tell BOFF where to find a list of symbolic declarations for the program being examined. In this way, BOFF can refer to certain locations in your program by name rather than by an octal address. For example, if you are using BOFF to examine an abort file, BOFF can use the symbol declarations to tell you the name of the routine in which the abort occurred and can give you a traceback of the various functions which called that routine. Without symbol tables of some kind, BOFF could only give octal addresses; this would make it much more difficult to identify the location in the source code where the problem occurred.
Normally, load modules prepared by the B, C, and Pascal compilers contain their own symbol tables. Thus there is no need to specify the "S=" option when using BOFF in Patch or Run mode, since BOFF can obtain the tables right from the load module. In the interests of saving space however, B, C, and Pascal modules release their symbol tables as soon as they begin execution; therefore, if you are using BOFF to examine an abort file, the symbol tables will no longer be present in the program. They will have to be obtained from the original load module by using the option "s=filename" on the BOFF command line, where filename is the name of the file that contained the module. If this file happens to contain more than one load module, you should specify "s=filename,modulename".
The same technique described above can be used to specify files that contain symbol tables when using BOFF in either Patch or Run mode. As we mentioned earlier, this is usually unnecessary because the load modules already contain their own symbol tables. If the programs were compiled with the "-Tables" option, they will not contain symbol tables for local (auto) variables; however, they will always contain tables for global (external) variables and function names.
There are times when it would be useful for BOFF to know more names than are contained in the standard symbol tables. Furthermore, if you are using BOFF to examine a load module that was not prepared with B, C, or Pascal, there may not be any standard symbol tables available. In such cases, you can supplement the information available in the load module by specifying a sequential file in the "s=filename" option.
When the file in the "s=" option is RANDOM, BOFF assumes that it is a load module with symbol tables in the standard format; however, when the file is SEQUENTIAL, BOFF assumes that the file contains text that declares a number of names to be associated with memory addresses. Each line of text should have the following format:
name [=] expression [;]
(The square brackets around the "=" and ";" indicate that they are optional. The ";" on the end can actually be any delimiter that cannot be part of a valid expression.) Standard
/* comments */
on single text lines are ignored, but comments cannot be continued from one line to the next.
BOFF will evaluate each given expression and will then associate the name with the corresponding address in memory. For example, suppose the declaration
A 10;
is found in the sequential symbol file. BOFF would associate the name "A" with location 10 in memory. If you later said "A=20" while working with BOFF, it would place the number 20 in memory location 10; it would NOT change the address value that is associated with the symbol "A". You might think of the lines in the "s=" file to be declarations of the locations of a number of external symbols; thus when you later assign a value to the symbol, it does NOT change the symbol's address but rather places the specified value in the address that is associated with the symbol.
The expressions given in the sequential symbol file should be constant expressions. Therefore they may only contain constants and symbols that have been defined previously in the symbol file; for example, you could say
A 10; X = A + 1;
The symbol "X" would then be associated with memory address 11. All standard B operators may be used in these expressions. However, it is very important to note that the indirection and addressing operators "*" and "&" are IGNORED when processing a sequential symbol file. Thus the following lines are all equivalent.
Y = X + A; Y = *X + A; Y = *X + &A Y = &X + &A
With "X" set at 11 and "A" set at 10, all four lines would set "Y" at 21.
Sequential symbol files may be specified when using BOFF in any mode. One particularly good use of these symbols might be when examining a load module that was not prepared with B, C, or Pascal. If a load map is available for the module, it should be comparatively easy to edit the map with a text editor like FRED and thereby create a sequential file declaring the various loader symbols in the format BOFF requires. Passing the edited file with the "s=" option allows BOFF to use all the given names and locations even though the standard tables are not present in the load module itself.
Copyright © 1996, Thinkage Ltd.