Microsoft KB Archive/62459

= (Complete) Stub File Description and How They May Enlarge EXE =

Article ID: 62459

Article Last Modified on 8/16/2005

-

APPLIES TO


 * Microsoft BASIC Professional Development System 7.0
 * Microsoft BASIC Professional Development System 7.1

-



This article was previously published under Q62459



SUMMARY
The stub files provided with Microsoft Basic Professional Development System (PDS) versions 7.00 and 7.10 should be used only under specific circumstances. If used incorrectly, linking with the stub files may actually increase the size of the executable file. This article explains when to link with stub files, the effects of each of the stub files, and when linking each stub file may increase or decrease the size of a program.

This information applies to Microsoft Basic Professional Development System (PDS) versions 7.00 and 7.10 for MS-DOS.



When to Use Stub Files
Most stub files are only useful when you are compiling for use with BCL7nxxx.LIB (compiling with BC /O) or making a customized run-time module. When you compile for use with the default BRT7nxxx.EXE run-time module, the support for Basic language features is already built into the run-time module and cannot be stubbed out without rebuilding (customizing) the run-time module itself.

Two exceptions to this are NOEMS.OBJ and OVLDOS21.OBJ, which affect overlay support. The overlay support is in the user .EXE program, even when compiled to use the run-time module, since the overlay manager must be the first code executed at run time. Thus, the NOEMS.OBJ and OVLDOS21.OBJ stub files are not put in the run-time module; instead they affect the Basic executable .EXE program.

How Stub Files Work
The Basic libraries (BRT7nxxx.LIB libraries) contain most of the support for Basic language features. When you use a Basic statement, such as &quot;PRINT&quot;, the compiler generates a call to a routine in the library that supports the feature. This is called an &quot;external reference&quot; because it is a reference to a routine outside of the module being compiled. At link time, the linker resolves the external references by linking in the called routine from the Basic libraries. Under certain circumstances (explained below), routines that are not actually needed are linked in from the Basic libraries. In this case, these unneeded routines can be &quot;stubbed out&quot; by linking in a stub routine with the same name, but which has essentially no code. Normally, a stub routine just immediately returns and generates an error. Linking in the stub routine prevents the default routine in the Basic library (which is much bigger than the stub routine) from being linked in, thus reducing the size of the program.

Why Linking with Stub Files May Increase .EXE Size
The BC.EXE compiler will only generate calls to Basic run-time library routines if they are needed. If support for a certain feature is not needed, it will not be linked in. This means that at link time, only those parts of the BCL7nxxx.LIB library that are needed will be pulled out of the library and linked with the program. If a feature has not been pulled out of the library but the stub file for that feature is linked in anyway, the linker must link in the routines in the stub file, which increases the size of the program. Essentially, this forces code to be linked in when otherwise it would have been left out of the .EXE altogether.

For example, if a program never uses the SCREEN or WIDTH statements or any graphics routines, the compiler will not generate any calls to graphics routines. This means that no graphics support will be pulled out of the BCL7nxxx.LIB libraries and linked with the program. In this case, linking with the NOGRAPH.OBJ stub file would increase the size of the program. The stub file contains stub routines that do have a minimal size. When you link with a stub file, the linker has no choice but to link all the routines in the stub file. If you are not actually stubbing anything out, linking in the stub routines will increase the size of the .EXE file.

Linking with stub files is only useful when the linker must pull support for a feature out of the libraries, but you know that your program does not need that feature. In this case, linking with a stub file will reduce the size of the final .EXE program. The sections below tell when each of the stub files should be used to decrease the size of the program.

When to Use the NOxxx.OBJ Graphics Stub Files
When you code any graphics SCREEN mode, the compiler knows to generate code that will require support only for that mode. Therefore, the linker will only link in support for the screen mode that you are using. If you only use SCREEN 9, the linker will only pull the EGA graphics support out of the Basic libraries.

The one time when all graphics support will be linked with your program is if you use SCREEN with a variable such as the following: SCREEN X% In this case, the compiler does not know what graphics mode you will be using until run time. Therefore, it is forced to generate code that will cause ALL of the Basic graphics support to be linked in. In this case, you would use NOGRAPH.OBJ, or one or more of the following stub files, to stub out support for those modes you will not be using:

NOCGA.OBJ, NOEGA.OBJ, NOOGA.OBJ, NOHERC.OBJ, NOVGA.OBJ

NOGRAPH.OBJ would only be useful if you are using SCREEN X%, where X% is guaranteed to be zero. NOGRAPH.OBJ is only useful when building custom run-time modules that will not support graphics. NOGRAPH is a superset of all the other above graphics stub files and cannot be linked with any of them.

When to Use NOCOM.OBJ or NOLPT.OBJ
Normally, support for communications or printing will not be linked in unless an OPEN &quot;COMx:&quot; or OPEN &quot;LPTx:&quot; statement exists in the program. However, if the program contains a statement that resembles the following OPEN A$ FOR as #n then the compiler must assume the A$ might be equal to &quot;COMx:&quot; or &quot;LPTx:&quot; at some time during the program. Therefore, communications and printing support will be linked in along with all other file support. If A$ will never be used to open the &quot;COMx:&quot; port or the printer, then the NOCOM.OBJ support module can be used to stub out support for communications and NOLPT.OBJ can be used to stub out printer support. This should reduce the size of the .EXE program.

When to Use SMALLERR.OBJ
SMALLERR substitutes smaller error message text strings for the normal error messages and maps the Basic error messages down to a few messages. Use this only in a program known to be very stable.

When to Use 87.LIB
87.LIB could increase the size of the .EXE if the program does not contain any math statements at all. However, use the 87.LIB stub file (in the .OBJ argument list of LINK, even though it is a .LIB file) to decrease the size of the .EXE file when the program contains a math statement and will be run ONLY on machines with a math coprocessor.

When to Use NOEVENT.OBJ
The NOEVENT.OBJ stub file is useful only to reduce the size of a customized run-time module that will not support event trapping. NOEVENT.OBJ is NOT useful for reducing the size of your compiled Basic .EXE program.

If the program can be compiled without /V and /W, the program doesn't require event trapping. In this case, mistakenly linking your Basic .OBJ modules directly with NOEVENT.OBJ may increase program size. If the program requires /V or /W, you would also not want to link with this stub file, since NOEVENT.OBJ is only useful for making customized run-time modules.

When to Use NOEMS.OBJ
In an overlaid program, this stub file will prevent the overlay manager from using expanded memory (EM) even if EM is present. This stub could be used if the program needed to use EM for other purposes (such as ISAM) and did not want the overlay manager to use EM. This stub file reduces code size only by about 1000 bytes. Do not use this stub file if the program does not contain overlays or if it is an OS/2 protected mode program.

OVLDOS21.OBJ
This stub file adds support for MS-DOS version 2.10 to an overlaid program. Any overlaid program that would want to work on MS-DOS 2.10 must have this file linked with it. OVLDOS21 is not needed (and should not be used) if the program is not overlaid or if it is a protected mode program. The stub file does not remove code, but always adds code and functionality (about 500 bytes).

When to Use NOFLTIN.OBJ
Replaces the INPUT code with an &quot;integer only&quot; version. If you link with this stub file, all forms of numeric input (INPUT, INPUT #, VAL, and READ) will have the following restrictions:

 READ, INPUT, INPUT #, and VAL will no longer recognize leading base specifiers on numbers. The following specifiers are illegal:

&H &O, &

 READ, INPUT, INPUT #, and VAL will no longer recognize trailing type specifiers on numbers. The following specifiers are illegal:

!, %, #, & and @

 READ, INPUT, INPUT #, and VAL will no longer parse a number with either a decimal point, E, or D in them. Thus, while 1E3 is a legal Basic integer, it will not be recognized. Using a SINGLE precision, DOUBLE precision, or CURRENCY variable with READ, INPUT, INPUT #, and VAL will cause the math support to be linked in. The restrictions in points 1-3 above will still hold. Also, using any other math related operation will pull in the support pack without lifting the restrictions of 1-3.

The main size advantage to using this stub file occurs when READ, INPUT, INPUT#, or VAL are the only statements that use the math package. This stub file will then eliminate at least 11K of code. If some other statement also needs the math package, the savings will be less than 2K.

When to Use NOEDIT.OBJ
This stub file replaces the editor used with the INPUT and LINE INPUT statements. It removes the following functions from the editor:


 * 1) No control character commands are recognized except for ENTER (done editing) and BACKSPACE (removes the last character). All other control characters are ignored, as are INS, DEL, HOME, END, and the arrow keys. Function keys will still expand because this functionality is performed outside the INPUT editor.
 * 2) If output is redirected (using >) and input is not redirected (no <), no characters will be echoed to the screen. The normal INPUT editor will print the characters as you types them in this situation.
 * 3) No characters will be echoed to the line printer even if line printer echoing is turned on.

You can obtain a 1K reduction in .EXE size using this stub file. Linking with this file could increase program size if the program never uses INPUT, LINE INPUT, LINE INPUT #, RANDOMIZE. If the program does not have INPUT or LINE INPUT statements but does have LINE INPUT # or RANDOMIZE (with not parameters), there will still be some savings.

When to Use the TSCNIOxx.OBJ Stub Files
NOTE: The statements affected by this stub file are subject to change in future versions.

The TSCNIOxx.OBJ file provides a smaller, simpler text output package. When it is linked in, the following differences from standard Basic will occur:

 No graphics statements are supported. All the following statements and functions will generate an illegal function call:

CIRCLE, POINT statement, POINT function, PAINT, PSET, VIEW, VIEW SCREEN, WINDOW, PALETTE, PALETTE USING, DRAW, PUT (graphics), LINE, PCOPY, PMAP, GET (graphics)

 VIEW PRINT will not be supported. All programs will have an implicit VIEW PRINT 1 TO <screen-size - 1> as is the normal default. For programs linked with this stub file, the only way to reach the bottom screen line is with the LOCATE statement, since the VIEW PRINT statement is not available.</li> There will be no support for function key display. The KEY ON/OFF/LIST statements will generate an illegal function call. CTRL+T to an INPUT statement will be silently ignored. Softkey definition and expansion will still be supported.</li> The COLOR statement will not accept a border parameter. Also, the color parameters are sent directly to the hardware. Thus, on an EGA or VGA card with a monochrome monitor, many values for COLOR will cause text to not be visible.</li>  Embedded control characters will not be supported for PRINT. Currently, the following features (which need to be added to the manual) are supported for the nonstubbed version of the PRINT code: <pre class="fixed_text">   Control Character  Description -  ---

CTRL+G    Beeps the speaker

CTRL+I Moves the cursor to the next tab position, erasing characters

CTRL+J Moves the cursor to the beginning of the next line

CTRL+K    Moves the cursor to the top-left corner of the current VIEW PRINT window

CTRL+L    Clears the VIEW PRINT window, homes the cursor within it

CTRL+M Moves the cursor to the beginning of the next line

CTRL+\    Moves the cursor to the right one space, stopping at                the end of the line

CTRL+] Moves the cursor to the left one space, stopping at                the beginning of the line

CTRL ^ Moves the cursor up one line, stopping at the top of                the VIEW PRINT window

CTRL_  Move the cursor down one line, stopping at the bottom of the VIEW PRINT window </li> The SCREEN and WIDTH statements will not be supported. The program will use whatever screen mode was available on start-up, unless it is a graphics mode, in which case an attempt will be made to determine if any text mode can be run in that graphics mode. The screen will always be 80 columns, displaying on video page 0. The number of lines will be determined by start-up conditions. The screen state will not be restored when the program terminates.</li> CLS will not accept any parameters.</li> Underline cursors on an EGA card not in 25-line mode may not be handled properly.</li> This stub file may not be used to build a customized run-time module. It may not support the CHAIN statement.</li> This stub file does not support CGA snow elimination during screen output.</li></ol>

This &quot;set&quot; of stub files is dependent upon operating system and near/far string support. Thus, there are four different versions of the file: <pre class="fixed_text">  File           Description ---  TSCNIONR.OBJ   Near string MS-DOS version TSCNIOFR.OBJ  Far string MS-DOS version TSCNIONP.OBJ  Near string OS/2 version TSCNIOFP.OBJ  Far string OS/2 version Any program linked with one of these stub files should decrease in size. The size decrease should be between 1.3K and 4.4K depending on the statements used in the program and the library being linked with.

When to Use the NOTRNEMx.LIB Stub File
NOTRNEMR.LIB and NOTRNEMP.LIB remove support for transcendental operations, including: SIN, COS, TAN, ATN, LOG, SQR, EXP, ^ (the exponential operator), a CIRCLE statement with a start or stop value, and the DRAW statement with the A or T commands.

When to Use the NOISAM.OBJ Stub File
NOISAM.OBJ removes ISAM functionality from customized Basic run-time modules. NOISAM.OBJ is not useful when linking stand-alone (BC /O) Basic executable programs.

Additional query words: BasicCom STUB700

Keywords: KB62459

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.