ࡱ>      q Qbjbjt+t+ mkAAC ]ttttttttH0 d XRD(lg!g!g! V V V V;FV4zW4X$9Z-\tXtg!g!g!g!XTtt DTTTg!p3tt Vttttg! VT2T Vtt V@c&T VCopyright WarpLink has been released to public domain and all copyright restrictions are removed by the original copyright holder, Michael Devore. WarpLink xe "License Agreement:WarpLink"License Agreement WarpLink has been released to public domain and no license agreement applies. Warrantyxe "Warranty" WarpLink has been released to public domain and has no warranty of any kind whatsoever xe "Return policy"Return Policy WarpLink has been released to public domain and no return policy applies Table of Contents  Basic Featurestoc \f C \e 1-1  Chapter 1. Introduction 1 Chapter 2. Using WarpLink 3 Chapter 3. Response Files 5 Chapter 4. Environment Variables 11 Chapter 5. Using Overlays 15 Chapter 6. WarpLink Options 19 Chapter 7. Using WarpLink with Clarion 2.1 55 Utilities Chapter 8. WarpMod Utility 57 Chapter 9. WarpSpeed Profiler 59 Chapter 10. Interactive WarpLink Utility 75 Chapter 11. WarpHog Utility 79 Chapter 12. WarpConv Utility 81 Chapter 13. Clipper Symbol Table Compaction Utility 83 Chapter 14. SmartMem Functions for Clipper Summer '87 87 Chapter 15. Norton Guides Help System 95 Advanced Features Chapter 16. Direct Library Module Specification 97 Chapter 17. Using D-format Dynamic Libraries 99 Chapter 18. Other WarpLink Features 107 Chapter 19. Using Overlay Pool Sizes Below Minimum Required 113 Help Chapter 20. Common Questions and Answers About WarpLink 117 Chapter 21. Troubleshooting and Problem-Solving 121 Chapter 22. Warplink Technical Support 125 Index 127  PRIVATE Chapter 1. tc \l 1 "Chapter 1. " Introduction  What is WarpLink? WarpLink is a DOS-compatible linker that is designed to be used with many different languages that produce standard Microsoft Link-compatible object files (.OBJ). WarpLink is much more than that, however. It also provides: 1. Dynamic overlays. Your programs require less memory and run very efficiently because of the way in which code is swapped in and out of memory. 2. Improved functionality of your program. WarpLink allows overlaid functions to call other overlaid functions, nesting down to any level. Also, WarpLink can overlay small model code with direct near calls between different overlays. 3. Fast linking. WarpLink is much faster than most linkers, so you will save time while linking programs. 4. Enhanced memory use for linking. WarpLink uses extended memory or expanded memory during link time to greatly improve linker performance. 5. Enhanced memory use during execution. WarpLink takes advantage of upper memory, extended memory and expanded memory while your program is running for lower memory requirements and faster program execution. 6. Very specific error handling. WarpLink not only tells you what is wrong, but also describes the error and offers solutions to fix the problem. 7. Clipper-specific functions. Incremental linking dramatically reduces your link time to fractions of a second by re-linking only those modules which have changed. WarpLink also has automatic compaction of your Clipper program symbol tables for greater memory savings. Or, you can use the stand-alone compaction utility. Add automatic overlaying of Clipper-compiled code in CLIPPER.LIB for greater memory savings. Most importantly, Warplink overlays C and assembly language modules in both Clipper runtime and third party libraries for memory savings that range from 30K to 100K or more over the versions of PLink and RTLink that are bundled with Clipper. 8. Powerful Clarion overlaying ability. Overlay local and static Clarion data, in addition to Clarion code, for greater memory savings than are possible with any other linker. WarpLink also supports the same EMS and XMS memory saving and speed increasing options for Clarion as it does with other languages. 9. EXE2BIN replacement. WarpLink can create .COM files directly from .OBJ files, instead of requiring the extra step of running EXE2BIN. 10. Extraction of individual modules from a library file at link time. You overlay portions of a library and leave other portions nonoverlaid. There is no need to use library manager utilities just to extract a few modules. 11. Dynamic link libraries for DOS. The proprietary D-format Dynamic Libraries (DDLs) allow true runtime dynamic linking under DOS with any language that WarpLink supports. DDLs support both overlaid and nonoverlaid code. Up to fifteen dynamic libraries are allowed for each program. 12. The WarpSpeed profiler. It provides you with powerful capabilities for analyzing your programs while running them in order to make speed and performance improvements. 13. Other valuable utilities. WarpMod allows you to modify runtime parameters without relinking. Interactive WarpLink automates the linking process and builds link files for you. The WarpHog utility simulates lower free memory conditions on your machine for testing purposes. Extra utilities include SmartMem subset for Clipper Summer '87 memory problems, WarpConv for translating script files from other linkers, and the Norton Guides help system. 14. Other features. A predefined $$_COM_END variable allows use of a .COM file to determine its own size while running. $$_EXE_IMAGE_SIZE is a corresponding variable for .EXE files. Support for six linker environment variables increases linking flexibility. Expanded .MAP files help track down particularly nasty bugs. Overlay manager hooks enable you to write your own overlay manager error handlers and dynamically transfer the overlay file to other drive and directories. PRIVATE Chapter 2. tc \l 1 "Chapter 2. " Using WarpLink  Operate WarpLink from the DOS command line or a batch or make file. There are no menus and operating modes. You simply type warplink followed by your specific command options and one or more filenames. WarpLink will be very familiar to users of TLink or Microsoft Link. WarpLink Format Use the following format for running WarpLink from the DOS prompt: WARPLINK [command options] OBJECT_FILES[,[program_file] [,[map_file][,[library_files]]]][;] The square brackets mean an item is optional. Do not use the brackets. Replace [command options] with any of the linker command options. (You will not actually enter the word options.) Remember that since [command options] is surrounded by brackets, you do not need to use command options when running WarpLink. Replace OBJECT_FILES with a list of one or more object file names. You must specify at least one xe "Object file"object file, except when using D-format dynamic libraries. When listing more than one, separate the names with plus signs (+) or spaces. The default extension for object file names is xe ".OBJ file".OBJ. Place overlaid object files in parentheses or brackets. Replace program_file with the name of the .EXExe ".EXE file" or xe ".COM file".COM file WarpLink creates as output. The default extension for program file names is .EXE . A .COM file is created if you specify the /c option when running WarpLink. If you do not specify a program file, WarpLink uses the name of the first object module with the extension .EXE (or .COM, when using the /c option). Replace map_file with the name of the text file that WarpLink creates to contain information about the .OBJ and xe ".LIB file".LIB files. For example, a text file may contain a list of all public symbols. The default extension for map file names is .MAP. xe "Map files:Use of"Map files are helpful debugging and profiling tools. If you do not specify a program file and you use the /m or /mx option, WarpLink uses the name of the first object module with a xe ".MAP file".MAP extension. Replace library_files with a list of one or more xe "Library file"library file names. To list more than one, separate each name by a plus sign (+) or space. The default extension for library file names is .LIB. Place overlaid library files in xe "Parentheses"parentheses or brackets. Some languages, such as recent versions if Microsoft C, Clipper, and Force, embed the name of a default library in the .OBJ file while it is being created. WarpLink will use that default library name when linking. The /nd option of WarpLink disables the automatic use of a default library name that is embedded in the .OBJ and .LIB files. Refer to Chapter 6, WarpLink Options, for information about /nd. When entering more than one file name, you must use commas as shown. For example, when specifying a program name and a library name without a map file name, use two commas to separate the file names. However, do not use commas as separators between the same file types. In other words, do not place commas between multiple object file names or library file names. File Extensions WarpLink uses default extensions for the file options, object_files, program_file, map_file, and library_files. You may omit a file extension and WarpLink will look for a file by using the name given with the appropriate xe "File extensions:Default"default extension. The default extensions for various files are: PRIVATE File TypeDefault ExtensionProgram file.EXEProgram file (using /c).COMMap file.MAPObject file.OBJLibrary file.LIBOverlay file.OVLD-format dynamic library file.DDL In all cases except .OVL and .DDL files which are created automatically by WarpLink, you can override the default extension by the explicit use of a different file name and extension. The .OVL extension can only be changed by using the /on option. The .DDL extension cannot be changed. NOTE: Refer to Chapter 6, WarpLink Options, for more information about the available options. PRIVATE Chapter 3. tc \l 1 "Chapter 3. " Response Files  You can store command options and file names that you have entered on the DOS command in a xe "Response files"response file. Response files are often referred to as link files, command scripts, or script files. Using response files to localize link information may be easier than using batch files. xe "Linking:Using response file"Linking with a Response File A xe "Response files:Linking with"response file replaces information typed following WARPLINK on the DOS command line. Rather than supplying option and file information to WarpLink on the DOS command line, you can place them in an ASCII text file, called a response file. Using a response file provides more flexibility when linking because there is no limit to the number of options and files you can list and no need to worry about typing errors with each link. To distinguish between an object or library file name and a response file name, precede the name of a response file with the at (@ )sign. This @ symbol designates the file as a response file instead of .OBJ file or .LIB file. Response File Format Use the following format for using a response file with WarpLink: WARPLINK @FILENAME.EXT The line length for a response file must be 127 characters or less. When using response files, you must specify the file extension if one is desired. WarpLink does not assume a .LNK or .RSP file extension. Using a Response File A response file contains exactly what you would type after WARPLINK on the DOS command line. For example, assume you have a response file called DBULINK.LNK containing the following two lines: DBU+DBUVIEW+DBUSTRU+DBUEDIT+DBUINDX+DBUCOPY+DBUUTIL+ DBUHELP,,,CLIPPER+EXTEND When DBULINK.LNK is used as a response file, WarpLink will look for the following .OBJ files: DBU.OBJ DBUEDIT.OBJ DBUUTIL.OBJ DBUVIEW.OBJ DBUINDX.OBJ DBUHELP.OBJ DBUSTRU.OBJ DBUCOPY.OBJ In this example, a program file is not specified so the file DBU.EXE will be created and named after the first object module (DBU.OBJ) but it will use the .EXE extension. Neither a map file nor options are specified, so a map file will not be created. WarpLink will look for two libraries, CLIPPER.LIB and EXTEND.LIB. Notice that none of the .OBJ or .LIB files are in xe "Parentheses"parentheses. This means that no overlays are used. xe "Clipper:DBU program"Clipper users will recognize the previous example as one of the sample programs that comes with Clipper. This program is a link response file that is used to create DBU.EXE. (The .OBJ files themselves do not come with WarpLink. They are shown here to illustrate a typical response file.) To link and create the program DBU.EXE, enter the following at the DOS command line: WARPLINK @DBULINK.LNK Response Files and Command Line Options You can mix and match command line options with a xe "Response files:With command line options"response file. For example, assume you have a response file called DBULINK2.LNK that contains the following two lines: +(DBUVIEW+DBUSTRU+DBUEDIT+DBUINDX+DBUCOPY+DBUUTIL+DBUHELP)+ OVLMGR,,,CLIPPER+EXTEND The difference between this example and DBULINK1.LNK (above) is that the first filename (DBU) is missing and the overlay manager file is included. To link DBU.EXE you would enter the following at the command line: WARPLINK /R /OP:M DBU @DBULINK2.LNK The response file picks up right where your entry leaves off by appending the first plus sign (+) to DBU as if the response file and command line were one. Since a program file name is not specified, the file DBU.EXE file will be created from the first object module name DBU.OBJ. A map file name and options are not specified, so a map file will not be created. WarpLink will look for two libraries, CLIPPER.LIB and EXTEND.LIB. Notice that in this example response file, all of the .OBJ files are in xe "Parentheses"parentheses. This means that they will be overlaid. When overlaying files, the corresponding overlay manager file name (OVLMGR.OBJ, C5OVLMGR.OBJ, or CNOVLMGR.OBJ) must be included in the object file list. Using Multiple Response Files You cannot nest one xe "Response files:Using multiple files"response file inside another. However, you can use multiple response files by listing them, one after another, on the command line. As long as one response file does not interrupt WarpLink processing you can list as many response files as will fit on the command line. You can intersperse commands with response files as desired. WarpLink processing will be interrupted if the response file contains a semi-colon (;) termination character, improper use of a comma to separate file names, or improper use of a plus sign (+) to continue a line. For example, assume you use three xe "Clarion:Linking example"Clarion response files: CLARESP1.LNK, CLARESP2.LNK, CLARESP3.LNK. CLARESP1.LNK contains the following: /CLA /OP:M CLARION + CLARION0 + CLARESP2.LNK contains the following: MYOBJ1 + (MYOBJ2 + MYOBJ3 + MYOBJ4) CNOVLMGR,MYPROG,, + CLARESP3.LNK contains the following: CLARION1 + CLARION2 You could link the sample program MYPROG.EXE by using the following command: WARPLINK @CLARESP1.LNK @CLARESP2.LNK @CLARESP3.LNK The command sets the /cla and /op:m options and uses the three response files containing the Clarion object modules CLARION.OBJ and CLARION0.OBJ; the nonoverlaid program module MYOBJ1.OBJ; the overlaid program modules MYOBJ2.OBJ, MYOBJ3.OBJ and MYOBJ4.OBJ; and the libraries CLARION1.LIB and CLARION2.LIB. You could achieve the same results as the previous example by changing CLARESP2.LNK to the following: MYOBJ1 + (MYOBJ2 + MYOBJ3 +MYOBJ4) + CNOVLMGR + and entering the following at the DOS command line: WARPLINK @CLARESP1.LNK @CLARESP2.LNK,MYPROG,, @CLARESP3.LNK The xe "Interactive WarpLink"Interactive WarpLink utility allows merging of xe "Response files:Using multiple files "multiple xe "Response files :Merging"response files to create one larger file that contains all of the object modules, libraries, and options of each individual response file. Refer to Chapter 10, Interactive WarpLink, for more information. Multiple Line xe "Response Files:Multiple lines"Response Files To break up a response file into several lines, use a plus sign (+) at the end of the line for lists of .OBJ and .LIB files. Place commas on separate lines. The following example shows one way to break the first example: DBU+DBUVIEW+DBUSTRU+DBUEDIT+ DBUINDX+DBUCOPY+DBUUTIL+DBUHELP , , CLIPPER+ EXTEND Comments in a Response File You can use WarpLink to add xe "Comments"comments to a xe "Response files:Comments"response file. Comments may be especially helpful for large response files, sample response files, or response files which are not used very often. Use the pound sign (#) in the first column of a line to insert comments into a response file. The following example shows comments within the response file from the previous example: # HERE ARE THE OBJECT MODULES # DBU+DBUVIEW+DBUSTRU+DBUEDIT+ DBUINDX+DBUCOPY+ DBUUTIL+DBUHELP # # END OF OBJECT MODULE LIST, THE FINAL # LINE DID NOT HAVE A CONTINUING '+' # # NO EXECUTABLE FILE SPECIFIED, USE # FIRST .OBJ FILE NAME WITH A .EXE # EXTENSION BY DEFAULT # , # # NO MAP FILE CREATED # , # # HERE ARE THE LIBRARY FILES # CLIPPER+ EXTEND # NO MORE LIBRARY FILES # # # END OF RESPONSE FILE PRIVATE Chapter 4. tc \l 1 "Chapter 4. " Environment Variables  WarpLink can make use of six xe "Environment variables:List of"environment variables: ( LIB environment variable ( OBJ environment variable ( TMP environment variable ( WARPLINK environment variable ( DDLPATH environment variable ( OVL_SWAP environment variable The LIB Environment Variable The LIB xe "Environment variable:LIB"environment variable contains the name of one or more directories that are used if WarpLink does not find a .LIB file in the current directory. The LIB environment variable is identical to the OBJ environment variable except WarpLink searches for library files with the LIB environment variable instead of searching for object modules. For example, assume your current directory is C:\DEVEL. The following command links MYPROG.OBJ with the runtime library LIBFILE.LIB: WARPLINK MYPROG,,,LIBFILE Without setting a LIB environment variable, if LIBFILE.LIB is not in the C:\DEVEL directory, WarpLink issues a file not found error. To specify the location of your library files as either the C:\LIB directory or in the D:\DEVEL directory, set the LIB variable as follows: SET LIB=C:\LIB;D:\DEVEL When LIBFILE.LIB is not found in the current directory (C:\DEVEL), WarpLink searches the C:\LIB and D:\DEVEL directories for the library as well. The OBJ Environment Variable The OBJ xe "Environment variable:OBJ"environment variable contains the name of one or more directories that are used if WarpLink does not find a .OBJ file in the current directory. The OBJ environment variable is identical to the LIB environment variable except that WarpLink searches for object modules with the OBJ environment variable instead of searching for library files. For example, assume your current directory is C:\WORK. The following command links TEST.OBJ and DRIVER.OBJ with the runtime library WORKLIB.LIB: WARPLINK TEST DRIVER,,,WORKLIB Without an OBJ environment variable, if TEST.OBJ or DRIVER.OBJ are not in the C:\WORK directory, WarpLink issues a file not found error. To specify those object modules in the OBJ or WORK\SUPPORT directories on the current drive, set the OBJ variable as follows: SET OBJ=\OBJ;\WORK\SUPPORT When the TEST.OBJ and DRIVER.OBJ files are not found in the WORK directory, WarpLink searches the OBJ and \WORK\SUPPORT directories of the current drive as well. NOTE: You can specify a drive identifier if you wish WarpLink to search a directory located on a different drive. The TMP Environment Variable WarpLink creates a temporary file on disk when memory gets low. This file is normally written to the current directory. To specify that the temporary file be created on another directory or disk (for example, a RAM disk) use the TMP xe "Environment variable:TMP"environment variable. For example, assume you normally link in the C:\CLIPPER directory. The following command creates the temporary file, if any, on drive F: SET TMP=F: NOTE: If an invalid drive or directory is specified using the TMP environment variable, it will be ignored and the temporary file will be created in the current directory. The WARPLINK Environment Variable The WARPLINK xe "Environment variable:WARPLINK"environment variable allows you to preset WarpLink command options. For example, assume you are a Clarion developer and you always need to use the /cla option and the minimum overlay pool value. The following command will direct WarpLink to use the /cla and /op:m options when linking: SET WARPLINK=/cla /op:m You can override the WarpLink environment variable by specifying an option at link time, either in a xe "Response files"response file or at the DOS command line. For example, a link using the option /op:40 in a response file would set the overlay pool size to 40K and override the /op:m setting in the previous example. The DDLPATH Environment Variable The DDLPATH xe "Environment variable:DDLPATH"environment variable allows you to specify the location of DDL files at runtime. When a program using DDL files runs, it looks for its supporting DDL files in the current directory and then in the paths specified by the DDLPATH environment variable. For example, assume a program uses DDL files. The following command directs WarpLink to look for supporting DDL files in the C:\DDLFILE directory: SET DDLPATH=C:\DDLFILE As with the LIB and OBJ environment variables, you can specify more than one directory to search by separating each name with semi-colons. The OVL_SWAP Environment Variable The OVL_SWAP xe "Environment variable:OVL_SWAP"environment variable is only for Clarion users. It allows an overlaid program to change the default swap file name. See Chapter 7, Using WarpLink with Clarion 2.1, for more information. PRIVATE Chapter 5. tc \l 1 "Chapter 5. " Using xe "Overlays:Using"Overlays  Overlays allow programs to run in less memory than they normally require. Overlays are pieces of your program that are loaded into memory by an overlay manager only when they are needed. They are removed by the overlay manager when they are finished and the memory they occupy is needed by other overlays. Instead of trying to shoehorn your entire program into memory at once, overlays leave parts of it on disk or in EMS (expanded) or XMS (extended) memory. The program pulls overlaid code into memory only when it is required. The WarpLink overlay manager loads as many overlays into memory as can fit into an area of memory called the overlay pool. The overlay pool is allocated when the program begins and can vary in size according to the overlay option settings. If the amount of memory you specify for the overlay pool is not available after the program loads, the WarpLink overlay manager will try to use a smaller amount, down to the minimum memory needed to load the largest overlay. Selection of overlays for the pool occurs dynamically, i.e., at runtime. Therefore, WarpLink is a xe "Overlays:Dynamic"dynamic overlay linker. WarpLink does not use the linktime, or xe "Overlays:Static"static, overlay schemes that some other linkers use because they can require loading only one overlay at a time, carefully planning where each overlay will load in a program, and leaving one or more overlay area "holes" in a program. Dynamic overlay schemes usually perform faster and make much more efficient use of memory than static ones. Specifying Overlays To use overlays, you must link in the object module containing the runtime overlay manager that is supplied on the WarpLink diskette. To specify which object modules or libraries are to be overlaid, place their names in xe "Parentheses"parentheses and follow the standard format for using WarpLink. The following example shows how to specify use of overlays with WarpLink: WARPLINK /OP:M NONOVL (OVL1+OVL2) (OVL3) (OVL4) OVLMGR,OVLPROG,,LIB1 (LIB2) This example creates the program OVLPROG.EXE from the object modules NONOVL.OBJ, OVL1.OBJ, OVL2.OBJ, OVL3.OBJ, OVL4.OBJ and OVLMGR.OBJ, and the libraries LIB1.LIB and LIB2.LIB. All object modules except NONOVL and OVLMGR are placed into overlays, along with the LIB2 library. Nonoverlaid code is said to be in the xe "Overlays:Root"xe "Root:Defined"root. In this example, code from NONOVL.OBJ, OVLMGR.OBJ, and LIB1.LIB is in the root. Clipper 5 Users Use the overlay manager object module named C5OVLMGR.OBJ on the WarpLink diskette when using overlays. Clarion 2.1 Users Use the overlay manager object module named CNOVLMGR.OBJ on the WarpLink diskette when using overlays. Note All other languages, including Clipper Summer '87, require the standard OVLMGR.OBJ overlay manager object module when using overlays. Performance Issues Using xe "Overlays:Performance"overlays has one drawback. Programs incur a slight speed penalty when they are used. Since dynamic overlays are transparent to the executing program, the overlay manager takes extra time to determine whether or not a specific overlay is already in memory when the code in the overlay is called. If the overlay has been loaded, then only a slight increase of time is required, i.e., a few microseconds for each overlay call. If the overlay is not loaded, however, the delay can be more significant. The time depends upon where the overlay file resides, i.e., a hard disk, a floppy disk, EMS, or XMS. Overlay size also affects how fast overlays are loaded. A fast hard drive, EMS, and XMS usually require loading times of a few milliseconds. A floppy-based system with moderately large overlays can require a second or more. The WarpLink overlay manager is designed to keep the most often used overlays in the overlay pool as much as possible in order to reduce loading delays. You can reduce delays by stashing overlays in EMS and XMS for fast access. Also try to keep your code modular and place overlaid routines in smaller modules. Large overlays force more overlay swaps in the overlay pool and reduce runtime efficiency, as well as require a larger overlay pool. Try to keep your overlaid routines under 20K. (This can be checked by looking at segment sizes in the WarpLink map file by using the /m or /mx options.) When linking with overlays, WarpLink will print the largest segment size when it prints the minimum overlay pool size -- this usually corresponds to a module, function, or procedure name. Object module size is not always a good indicator of overlay size. With Clipper and Clarion code, for example, an object module can contain several segments that each go into their own overlay. Each procedure or function is a separate segment. Several WarpLink overlay options may be fine-tuned for better program performance when using overlays. Use the WarpMod utility and the WarpSpeed profiler to test overlay performance. Refer to Chapter 6, WarpLink Options; Chapter 8, WarpMod Utility; and Chapter 9, WarpSpeed Profiler, for more information. Technical Notes Only subroutines, procedures, and functions that are called and returned may be overlaid. (This includes all Clipper-compiled code.) The overlay manager stores return addresses on its internal stack when calling an overlay. Jumps from one overlay to another do not properly restore this stack. There are several types of code and modules which cannot be overlaid, including interrupt-handler routines and self-modifying code. Refer to the Overlay Technical Information section in Chapter 20, Common Questions and Answers About WarpLink, for a more detailed discussion about the types of code that cannot be overlaid. Place the overlay manager (OVLMGR.OBJ, C5OVLMGR.OBJ or CNOVLMGR.OBJ) in the root. It cannot be overlaid. Do not place startup code in an overlay. The overlay manager needs a fixed code address to begin program execution. The overlay manager assumes all code segment names end in 'CODE' except for Clarion. (Refer to the /cla option). If you use another segment name for your code, you must use the /oc option. If you are using small model code overlays, or your program contains overlays that call the root and then are swapped out by overlays called from the root, you may need to use the /r option or specify the overlays with xe "Brackets"brackets ([ ]). Refer to the Small Model Code Overlays and Overlay to Root Call Vectoring in Chapter 18, Other WarpLink Features, for more details. PRIVATE Chapter 6. tc \l 1 "Chapter 6. " WarpLink Options  xe "WarpLink:Options"WarpLink xe "Options:WarpLink"options allow you to control how your programs are linked and executed. You can specify these options from the DOS command line, in a batch or make file, or in a WarpLink xe "Response files"response file. Options Format The following example shows the format for entering WarpLink options at the command line: WARPLINK [options] OBJECT_FILES[,[program_file][,[map_file] [,[library_files]]]][;] All options are case insensitive, e.g. both /c and /C refer to the create COM file option. Enter WARPLINK without parameters at the DOS command line for a summary of the linker options. Non-overlay xe "Link options:Non-overlay options summary"Options Summary PRIVATE OptionDescription/as:sizeSet maximum allocation space in paragraphs./bBeep the speaker upon exit./cCreate .COM file./clpfPerform full link after failed Clipper incremental link./clpiPerform Clipper-specific incremental link./clpp:sizeSet Clipper incremental link segment pad length in bytes./clpsUse Clipper SmartMem functions, SMARTMEM.XXX./dUse DOSSEG segment ordering./ddlCreate D-format dynamic library./dm:nameUse DDL manager data file name./emUse extended dictionary in Microsoft-compatible library./iDisplay link process information.OptionDescription/mCreate map file./mxCreate map file expanded version./ndDo not use default libraries./qlPerform QuickLinker link./sMake symbol names case sensitive./spPack symbol table for Clipper code./st:sizeSet program stack size in bytes./tf:nameSet temporary file name./udl:nameUse named D-format dynamic library at runtime./w0Set warning exit code to 0, instead of 1./wnDo not display warnings./xpUse expanded memory (EMS) during link./xtUse extended memory (XMS) during link. Overlay xe "Link options:Overlay options summary"Options Summary PRIVATE OptionDescription/claTurn on Clarion overlay compatibility mode./clp5[:name]Overlay Clipper 5 compiled CLIPPER.LIB modules./oc:[.]nameOverlay class name. Use leading . for exact match./ohp:[-]sizeOverlay stash in EMS, expanded memory. Use - to leave memory free./ohp3:[-]sizeOverlay stash in EMS, force version 3.0 compatibility./oht:[-]sizeOverlay stash in XMS extended memory. Use - to leave memory free./oiMake overlays internal to .EXE file./ol:countOverlay maximum load count.OptionDescription/on:nameOverlay file name./op:[-]sizeOverlay pool size in kilobytes. Use - to leave memory free./op:mUse overlay pool minimum required size./orpSwap active overlays at runtime to EMS 4.0 expanded memory./ortSwap active overlays at runtime to XMS extended memory./os:sizeOverlay manager internal stack size in kilobytes./ouPlace overlay pool in upper memory block (UMB)./ox[:e-var] Place overlay pool in expanded memory (EMS) page frame. (Use only if environment variable is set to the specified value.)/rReload active overlays swapped out upon return at same address. Options Details The WarpLink command options are described below in alphabetical order. Details and technical notes are included for each option. PRIVATE  /as:size Set maximum allocation space in paragraphs. Syntax Size is a value representing a number of paragraphs. The /as xe "Link options:/as"option sets the number of paragraphs, or sixteen-byte blocks, of memory allocated to a program after it loads, the default value is 65535. Size ranges from 0 to 65535. Description In most situations, the default value of 65535 for the maximum number of allocated paragraphs is the most appropriate for your program. This value will rarely need to be modified. However size can be modified after linking with the WarpMod utility as described in Chapter 8, WarpMod Utility. If the size is too low, WarpLink will set the value to the minimum required and display the following message: Maximum program allocation space less than minimum required, maximum adjusted. You may intentionally set size too low in order to automatically set the maximum memory used by a program to the absolute minimum needed when DOS loads the program. However, be aware that most languages require extra memory after the program begins operating for variable and buffer allocations. Setting the value to the minimum in these cases will cause the program to return an out of memory xe "Error:Out of memory"error. When using overlays, size must reflect the additional memory required for the overlay pool and overlay manager internal table and stack allocations. Technical Note This option corresponds to Microsoft Link's xe "Microsoft Link:/CP"/CP or xe "Microsoft Link:/CPARMAXALLOC"/CPARMAXALLOC option. PRIVATE  /b Beep the speaker upon exit. Description This xe "Link options:/b"option will cause WarpLink to beep your speaker three times at the completion of the linking process. Technical Note Three control-G characters are written to standard output (stdout) by this option. PRIVATE  /c Create .COM file. Description WarpLink generates .EXE files by default. The /c xe "Link options:/c"option directs WarpLink to create a .COM file directly. You cannot just create a .COM file at will. The compiler or assembler that generated the .OBJ file determines whether it can be a .COM or .EXE file. When in doubt, assume .EXE. On the other hand, if you omit the /c option on a file that should have been linked as a .COM file, you will get a no stack segment warning during the link as WarpLink creates a .EXE file with no stack segment. Technical Note You cannot use xe "Overlays:.COM files"overlays with a .COM file. PRIVATE  /cla Turn on Clarion overlay compatibility mode. Users The /cla xe "Link options:/cla"option can be used only by Clarion 2.1 programmers and is required when using overlays with Clarion 2.1. Description The /cla option indicates that xe "Clarion overlays"Clarion code is being overlaid. WarpLink automatically sets certain internal parameters and uses special processing routines that allow use of Clarion with overlays. The /cla option implies use of the /r option. You do not need to specify the /r option when using the /cla option. See Also Refer to Chapter 7, Using WarpLink with Clarion 2.1, for more information. Technical Note xe "Link options:/r"When the /cla option is used, the overlay class is changed to CLARION for segments with the name prefixes _CODE, _DT, and _DAT. Segments with matching suffixes (i.e. following these three prefixes) will be grouped into one overlay. For example, WarpLink will group _CODE_MOO_SEG, _DAT_MOO_SEG, and _DT_MOO_SEG together. Such grouping allows overlaying of Clarion local and static data along with Clarion code for greater memory savings. PRIVATE  /clp5[:name] Overlay Clipper 5 compiled CLIPPER.LIB modules. Syntax Name is the name of the xe "CLIPPER.LIB"CLIPPER.LIB library. Users The /clp5 xe "Link Options:/clp5"option can only be used by Clipper programmers. Description The /clp5 option instructs WarpLink to automatically overlay selected portions of the CLIPPER.LIB library for Clipper 5. These portions include all modules that contain compiled Clipper code. Using this option can reduce your memory usage by 2040K in addition to the savings created from overlaid CLIPPER.LIB modules written in C and assembly language that can be explicitly overlaid via direct library module specification. If the Clipper library has been renamed, name is the new library name that contains the overlaid Clipper compiled modules. It is an optional parameter but you must precede it by a colon if used. The /clp5 option must come before the library list on the WarpLink command line, otherwise a WarpLink internal error may occur. CLIPPER.LIB must be explicitly specified in the library list. In other words, if you use the /clp5 option and CLIPPER.LIB is specified implicitly through the default libraries WarpLink will fail with an internal error. /clp5 also works with Clipper Summer '87, but this option will only overlay the ERRORSYS module yielding a savings of 2K. PRIVATE  /clpf Perform full link after failed Clipper incremental link. Users The /clpf xe "Link options:/clpf"option can only be used by Clipper programmers. Description Use this option to automatically perform a full link if a Clipper-specific incremental link fails. By default, WarpLink prompts you to perform a full link if an incremental link fails. The /clpf option instructs WarpLink to bypass the question and automatically perform a full link when an incremental link fails for any reason. PRIVATE  /clpi Use Clipper-specific incremental link. Users The /clpi xe "Link options:/clpi"option can only be used by Clipper programmers. Description Use this option to take advantage of WarpLink's Clipper-specific incremental link capabilities. Incremental linking is a tool for rapid program development. It will drastically cut down on your linking time because only those object files which have been modified since the last link will be re-linked. xe "Incremental linking"Incremental linking is specified using the /clpi option. During the first run of a link using /clpi, a full link is performed and an incremental link file is created. The name of the incremental link file will be the name of the executable file, with a xe ".ILF files".ILF extension. The .ILF file contains information used during later links of the program. .ILF files must reside in the current directory in order for WarpLink to find them. WarpLink will attempt to do an xe "Linking:Incremental linking with Clipper"incremental link whenever the /clpi option is used and a .ILF file is present for the program. If no .ILF file is present, a new one will be built for use with the next incremental link. xe "Clipper:Incremental linking"Incremental linking works only with Clipper .OBJ files. If you change a non-Clipper object module or any library, the incremental link will fail and allow you the option of continuing with a full link. This will create a new .ILF file. WarpLink bases the decision to modify code using the incremental link upon the time and date stamp of a file. If the date or time stamp of a file has not changed since the last incremental link, WarpLink will assume that no code changes were made. You can change a symbol name, rearrange variables in the symbol table, and do some limited addition or deletion of symbol names and still have a successful incremental link. Exceeding the pad length with code changes, adding more than two new symbols, or changing the position of a procedure within a symbol table will force the incremental link to fail and require a full link. It is recommended that you perform a full link without the /clpi option on the final version of your software after development is complete. This will remove Clipper procedure and symbol table padding that is added during the incremental link process. Using the /clpi option will add to the size of your .EXE file. WarpLink must make allowances for new code in your .EXE file, so it adds some free space for later changes. See the explanation of the /clpp option for more complete information on this .EXE file padding. The /clpi and xe "Link options:/sp"/sp options cannot be used together. You cannot perform symbol compaction on a file that was linked incrementally. The option specified last will be used. If you use the /clpi option with direct library module specification, you must place the option before the library list in the link file. If these options are not placed before the library list, you will receive internal errors due to irreversible processing of the library modules that requires those options not be altered after libraries are processed. For example, these options execute successfully: WARPLINK /CLPI /OP:M /R OBJMODULE,EXENAME,,LIB1:MOD1 LIB2 Do not place the /clpi option after the library list as follows: WARPLINK /OP:M /R OBJMODULE,EXENAME,,LIB1:MOD1 LIB2 /CLPI PRIVATE  /clpp:size Set Clipper incremental link segment pad length in bytes. Syntax Size is the size of the segment pad value for incremental linking in bytes. It can range from 0 to 255. Users The xe "Link options:/clpp"/clpp option can only be used by Clipper programmers. Description This option directs WarpLink to change the size of the segment pad that is added during incremental linking. The default of 48 bytes is the number of bytes that you can safely add to each Clipper procedure after the initial full link without causing subsequent incremental links to fail. A non-zero xe "Incremental linking:Padding"pad value will increase the size of the Clipper procedures (in overlays or the root) in your program for incremental linking. The larger the pad value, the greater the increase. Every Clipper procedure (segment) is padded with the amount of bytes specified by the /clpp option. Padding in the root procedures will directly affect both the xe ".EXE file".EXE file size and the memory overhead of your program. Padding in overlaid procedures will only directly affect the overlay file size and not your program's memory requirements, except in those rare cases where the larger overlay size may cause your overlay pool size requirements to go up 1K or 2K, at most. The /clpp option is ignored by WarpLink if the xe "Link options:/clpi"/clpi option is not specified. After a program is incrementally linked, the original /clpp pad value will be used until the incremental link fails and a full link is performed. Changing the pad value from its original setting will have no effect during successful incremental links. PRIVATE  /clps Use Clipper SmartMem functions, SMARTMEM.XXX. WarpLink has been released to public domain. We do not have permission to release the licensed Smartmem subset to public domain, and those files are not included in this release. PRIVATE  /d Use DOSSEG segment ordering. Description The xe "Link options:/d"/d option allows you to force xe "DOSSEG"DOSSEG xe "Segment ordering:DOSSEG"segment ordering when linking your program. Since most languages that need DOSSEG segment ordering insert a flag in the object modules or libraries that instruct the linker to use DOSSEG segment ordering, this option is rarely required. However, it is available for those occasions where explicit DOSSEG segment ordering is necessary. Technical Note DOSSEG segment ordering structures programs as follows: ( All segments with a class name ending in CODE ( All other segments that are not of group DGROUP ( Segments of group DGROUP DGROUP segments are arranged in this order: ( All segments of BEGDATA class ( All segments not of BEGDATA, BSS, or STACK class ( Segments of class BSS ( Segments of class STACK DOSSEG adds 16 zero-filled bytes to the front of the first segment named _TEXT, if one exists. PRIVATE  /ddl Create D-format dynamic library. Description The xe "Link options:/ddl"/ddl option instructs WarpLink to create a .DDL D-Format dynamic library file out of the object modules and libraries that are listed with this option. The DDL D-Format dynamic library may be a support DDL file, a master DDL file, or both. You may specify overlaid and nonoverlaid modules for the DDL file, as well as whether the modules to be linked in are required when using the DDL file or optional. DDL files are independent of each other and they alone hold the information used to determine whether a particular module they contain is overlaid or not and is required or not. See Also Refer to Chapter 17, Using D-format Dynamic Libraries (DDLs), for more information. PRIVATE  /dm:name Use DDL manager data file name. Syntax Name is the name of the DDL manager file. Description The xe "Link options:/dm"/dm option supplies the WarpLink DDL manager file name to the DDL file being created. If the /dm option is not used, the default DDL manager file name is xe "DDLMGR.DAT"DDLMGR.DAT. WarpLink must always have a DDL manager file name present when creating a D-format dynamic library. The DDL manager file bound with the master DDL file will start and run your program using dynamic libraries. WarpLink searches the directories listed in the xe "Environment variable:OBJ"OBJ environment variable, if one exists, for the DDL manager file if WarpLink does not find it in the current directory. Clipper User Note The dynamic library managers currently do not perform automatic xe "Clipper:/dm link option"xe "Clipper:.CLP files"Clipper symbol table compaction. You may wish to create .CLP files to reduce the number of duplicate symbols in your program when using DDLs. Clipper 5 User Note The DDL manager file name for xe "Clipper 5:/dm link option"xe "Clipper 5:C5DDLMGR.DAT"Clipper 5 is C5DDLMGR.DAT. You must specify the /dm:C5DDLMGR.DAT option when using Clipper 5 with overlays. If you are not using overlays with Clipper 5 and DDLs, use the default DDLMGR.DAT file. Clarion 2.1 User Note The DDL manager file name for xe "Clarion:CNDDLMGR.DAT"xe "Clarion:/dm link option"Clarion is CNDDLMGR.DAT. You must specify the /dm:CNDDLMGR.DAT option when using Clarion with overlays. If you are not using overlays with Clarion and DDLs, use the default DDLMGR.DAT file. See Also Refer to Chapter 17, Using D-format Dynamic Libraries (DDLs), for more information. PRIVATE  /em Use extended dictionary in Microsoft-compatible library. Description The /em option directs WarpLink to use extra indexing in libraries. Some library (.LIB) files have extra indexing, referred to as xe "Libraries:Extended dictionary"an xe "Extended dictionary"extended dictionary, that helps linkers more effectively locate modules contained within the file. This can speed up link times in some cases, although WarpLink has been optimized to operate effectively even without extra indexing. Because this extra xe "Indexing"indexing can cause library modules to link into the program even if they no longer resolve a symbol reference, use of /em may link in multiple modules that define the same symbol. If this happens, then WarpLink will display a symbol has more than one public definition warning. The first definition of the symbol has precedence over any definitions that may follow. Some xe "Libraries:Borland library"Borland library files contain extra indexing, but use a format that differs from the Microsoft extended dictionary format. The xe "Link options:/em"/em option will not help with these files. Technical Note Microsoft Link and many other linkers default to using the extended dictionary in library files. If you do not wish to use the dictionary, then you must turn off the default by specifying a particular option (e.g. use the Microsoft Link options xe "Microsoft Link:/NOE"/NOE or xe "Microsoft Link:/NOEXTENDEDDICTIONARY"/NOEXTENDEDDICTIONARY). With WarpLink the situation is reversed. You must use /em to turn on use of the extended dictionaries. PRIVATE  /i Display link process information. Description This option provides information about the linker while it is working. You can use it to assure yourself that the linker is continuing during long links, to view something on the screen during a link, or to identify which parts of the link process take the most time. The xe "Link options:/i"/i option may help you troubleshoot any problems that occur when using WarpLink by narrowing down where the trouble spot lies. Entry to and exit from the main routines in the link process are displayed, as well as the file names of object files and library files currently being processed. You will typically notice that processing libraries takes up most of the linking time. PRIVATE  /m Create map file. Description A map file contains the size and placement of code, data, and stack segments in a program (in hex, or base 16) and program entry information. Use xe "Link options:/m"/m to create a xe "Map files:Contents"map file. WarpLink map files have the same format as those created by Microsoft Link. To get more detailed information, use the /mx option for expanded xe "Microsoft Link:Map files"map files. PRIVATE  /mx Create map file expanded version. Description The expanded map file option offers detailed map information that is useful for debugging and identifying space usage in each segment. Such information is handy for assembly language programmers who wonder why a segment is the wrong size, for example. xe "Link options:/mx"The map file might show that you left the trailing h off of a number that is supposed to be in hexadecimal. It is also good for detecting the source of a segment overflow (i.e., a segment larger than 64K). In addition to the information (created by /m) in a normal xe "Map files:Contents"map file, the expanded map file lists the names and addresses of public symbols as well as detailed individual program segment information. The WarpSpeed profiler uses the detailed map information when profiling programs. PRIVATE  /nd Do not use default libraries. Description Most language compilers and assemblers insert the name of one or more runtime libraries directly into their .OBJ files so that these libraries do not have to be explicitly specified on the linker command line. These .LIB files are called the xe "Default libraries"default libraries. You can prevent WarpLink from using the default libraries by using the xe "Link options:/nd"/nd option. The /nd option allows you to link programs without automatically linking in the default libraries. This may be useful when linking in replacement libraries or if you rename default libraries. PRIVATE  /oc:[.]name Overlay class name.  Syntax Name is the name of the code class to be overlaid. Use a leading period (.) to specify an exact match of the name. Description Most programming languages assign a class name to the program segments that they create. Classes are useful because linkers use them to determine segment order. All segments of a particular class are grouped together in a program. Keeping all initialized data in one area of the program allows easier references to all the data and helps to keep .EXE file size and program memory use to a minimum. Typical class names are CODE, DATA, BSS, and STACK. Usually, a language compiler or assembler generates class names automatically, although some languages allow the user to select a different class name. By default, WarpLink uses the xe "Segments:Class name"xe "Overlay:Class name"class name CODE for overlaid code. You can use the xe "Link options:/oc"/oc option to change the overlay class name should your program's object and library modules use a different class name. Follow the /oc: with the name of the class that your program uses for code segments which you wish to overlay. Any segment in an overlaid module which has a suffix of the name specified in the /oc option will be overlaid. If you wish to force an exact match on the name, rather than just a suffix, place a period (.) immediately before the name. Do not use /oc without good reason and an understanding of the implications within your program. The default setting should be maintained in almost all cases. Examples You wish to overlay two or more code segments of classes MY_PROG and YOUR_PROG in overlaid object or library modules. Specify /OC:PROG on the WarpLink command line. You have two or more segments as described in the example above, but you wish to overlay code segments of class MY_PROG only. Specify /OC:.MY_PROG on the WarpLink command line. Technical Note Do not use multiple overlay class names. The last overlay class name specified will be used by WarpLink. Clarion User Note Do not use the xe "Clarion:/oc option"/oc option with Clarion programs. Although Clarion programs use a code class name of CLARION rather than CODE, the /cla option instructs WarpLink to automatically handle this class name difference. PRIVATE  /ohp:[-]size Overlay stash in EMS 4.0, expanded memory.  Syntax Use - to leave memory free. Size is the size of the overlay stash in kilobytes. It can range from 0 to 16383. Description This option stashes the xe "EMS:Overlay stashing"overlay file to EMS memory at runtime. The overlays are stashed as they are loaded for the first time in the overlay pool, as memory allows. Thereafter, if the overlay must be reloaded, it will be brought in from EMS memory rather than from disk. Stashing can substantially increase speed in the executing program. Partial stashing of some overlays may occur if there is not enough memory to stash all of them. Overlays are placed in EMS on a first loaded, first stashed-as-fits, basis. All EMS memory allocated for use by xe "Link options:/ohp"/ohp is automatically freed at program termination. /ohp overlay file stashing will not occur if the overlay manager detects less than 80K free EMS or an EMS driver is not present. You should use a multiple of 16K to specify size because xe "EMS:Allocation"EMS pages are allocated in 16K pages. Odd amounts are rounded up. For example, /ohp:120 is the same as /ohp:128. A minus sign means leave the amount free. For example, /ohp:1024 means leave 1024K free (1M) for the executing program and use the rest for stashing overlays (up to the space required). The overlay manager will not take more EMS memory than it needs even if you specify more with the /ohp option. For example, if you specify /ohp:4096 and the overlay manager only needs 640K to stash the entire overlay file, the overlay manager will allocate only 640K of EMS. /ohp detects xe "EMS:4.0"EMS 4.0 automatically and uses an enhanced stashing algorithm if xe "EMS:Allocation"EMS 4.0 (supporting direct lower memory mapping) is available. The direct memory mapping algorithm is more speed efficient than the EMS 3.0 algorithm of copy-to-page map-out-page and map-in-page copy-from-page. /ohp is more useful than xe "Link options:/orp"/orp in a generic sense, but both can be used simultaneously. /orp will stash an exact image of a swapped-out, active overlay for return swap-in, thus eliminating the need for the overlay manager to process and fix up overlay offsets when the active overlay is brought back in. Typically, you will find a much greater speed increase with /ohp stashing, but /orp can also speed up a program if there are many active overlay swap-outs. /ohp allocates EMS after /orp does its 128K fixed allocation. If you have a small amount of EMS, it is recommended that you use /ohp rather than /orp. Use of the EMS page frame for the overlay pool (/ox) prevents EMS 3.0 overlay file stashing via the /ohp option. The xe "Link options:/ox"/ox option automatically shuts off such stashing because xe "EMS:3.0"EMS 3.0 routines must map into the EMS page frame that /ox uses to hold the overlay pool that the stashed overlay is being copied to. If you use /ohp and /ox, and the /ohp routines detect EMS 3.0 usage, then stashing an overlay file to EMS will be automatically shut off at runtime. Note that it is always safe to specify both the /ox and /ohp options. If the WarpLink overlay manager detects EMS 4.0 support, then simultaneous use of the EMS page frame for the overlay pool and stashing of the overlays to EMS occurs. If it does not detect EMS 4.0 support, then only the EMS page frame for the overlay pool will be used. The /ohp option has lower priority than the xe "Link options:/oht"/oht option if both are used. If you specify both the /oht and /ohp options, XMS overlay stashing will be used unless at least 80K of free XMS is not available, at which time the WarpLink overlay manager will attempt to use EMS for overlay stashing. You may wish to specify both options if your program will be operating on a mix of machines that may have either EMS or XMS memory. See Also Refer to the /orp, /ox, and /oht options for more information. Clipper User Notes An initial setting of /ohp:512 for xe "Clipper:/ohp option"Clipper programs is recommended. This guarantees 512K of EMS remains for your program, plus whatever may be left over from stashing the overlay file. In particular, it is not recommended that a Clipper 5 program have no EMS available to it during execution. If your program has no need for EMS, then use a large /ohp setting to stash the entire overlay file. For example, use a setting of /ohp:9000. If you use the /ohp option, the xe "Clipper 5 :CLD.EXE and options"Clipper 5 debugger CLD.EXE will not function with your program. Use WarpMod to turn this option off and on quickly, if necessary. PRIVATE  /ohp3:[-]size Overlay stash in EMS, force version 3.0 compatibility. Syntax Use - to leave memory free. Size is the size of the overlay stash in kilobytes. It can range from 0 to 16383. Description This option operates identically to the /ohp option except that it forces use of the xe "EMS:3.0"EMS 3.0 stashing algorithm. You may need to use /ohp3 because some EMS drivers incorrectly report xe "EMS:4.0"EMS 4.0 compatibility while not supporting direct lower memory mapping. The xe "Link options:/ohp3"/ohp3 option forces the overlay manager to use the less efficient EMS 3.0 technique even if version 4.0 EMS is detected. Since this may only be a problem on a few older 80286 and 8088/8086 machines, you should use /ohp3 only when necessary or in order to anticipate all possible problem scenarios. Unnecessary use of /ohp3 reduces efficiency and provides less speed increase at runtime, as compared to using the /ohp option. /ohp3 overlay file stashing will not occur if the overlay manager detects less than 80K free EMS or an EMS driver is not present. All EMS memory allocated for use by /ohp3 is automatically freed at program termination. Use of the xe "EMS:Page frame"EMS page frame as the overlay pool (/ox option) prevents EMS 3.0 overlay file stashing. The xe "Link options:/ox"/ox option automatically shuts off such stashing because EMS 3.0 routines must map into the EMS page frame that /ox uses to hold the overlay pool that the stashed overlay is being copied to. If you use /ohp3 and /ox, the /ohp3 setting is ignored by the overlay manager and only /ox setup will occur. See Also Refer to the /orp and /ohp options for more information. Clipper User Note If you use the /ohp3 option, the xe "Clipper:/ohp3"xe "Clipper 5:CLD.EXE and options"Clipper 5 debugger CLD.EXE will not function with your program. Use WarpMod to turn this option off and on quickly, if necessary. PRIVATE  /oht:[-]size Overlay stash in XMS extended memory. Syntax Use - to leave memory free. Size is the size of the overlay stash in kilobytes. It can range from 0 to 16383. This option stashes the overlay file to xe "XMS:Overlay stashing"XMS memory at runtime. The overlays are stashed as they are loaded for the first time in the overlay pool, as memory allows. Thereafter when reloaded, the overlay will be brought in from xe "XMS:Allocation"XMS memory rather than from disk. Stashing can provide substantial speed increases in the executing program. Partial stashing of some overlays may occur if there is not enough memory to stash all of them. Overlays are stashed on a first loaded, first stashed-as-fits, basis. xe "Link options:/oht"/oht overlay file stashing will not occur if the overlay manager detects less than 80K free XMS or an XMS driver is not present. Use a minus sign (-) to leave the amount free. For example, /oht:1024 means leave 1024K (1M) for the executing program and use the rest for stashing overlays, up to the space required. The overlay manager will not take more XMS memory than it needs even if you specify more with the /oht option. For example, if you specify /oht:4096 and the overlay manager only needs 640K to stash the entire overlay file, the overlay manager will allocate only 640K of XMS. All XMS memory allocated for use by /oht is automatically freed at program termination. /oht is more useful in a generic sense than xe "Link options:/ort"/ort but both can be used simultaneously. /ort will stash an exact image of a swapped-out active overlay for return swap-in, eliminating the need for the overlay manager to process and fix up overlay offsets when the active overlay is brought back in. Typically, you will find a much greater speed increase with /oht stashing, but /ort can also speed up a program if there are many active overlay swap-outs. /oht allocates XMS after /ort does its 128K fixed allocation. If you have a small amount of XMS, it is recommended that you use /oht rather than /ort. The /oht option has priority over the /ohp option if both are used. If you specify both the /oht and /ohp options, XMS overlay stashing will be used unless at least 80K of free XMS is not available, at which time the WarpLink overlay manager will attempt to use EMS for stashing. You may wish to specify both options if your program will be operating on a mix of machines that may have either EMS or XMS memory. See Also Refer to the /ort option for more information. Clipper User Note An initial setting of /oht:512 for xe "Clipper:/oht"Clipper programs is recommended. This guarantees 512K of XMS remains for your program, plus whatever may be left over from stashing the overlay file. Clipper cannot use XMS directly, but many memory managers, such as xe "QEMM"QEMM and xe "386^Max"386^Max, automatically convert XMS to EMS. It is not recommended that a Clipper 5 program not have EMS available to it during execution. If your program has no need for XMS or converted EMS, then use a large /oht setting to stash the entire overlay file. For example, use a setting of /oht:9000. If you use the /oht option, the xe "Clipper 5 :CLD.EXE and options"Clipper 5 debugger CLD.EXE will not function with your program. Use WarpMod to turn this option off and on quickly, if necessary. PRIVATE  /oi Make overlays internal to .EXE file. Description This xe "Link options:/i"option makes xe "Overlays:Internal"overlays internal to the .EXE file. Instead of creating separate .EXE and .OVL files, only one .EXE file will be created. The overlays will be placed at the end of the .EXE file. When the program is run, DOS will load only the nonoverlaid portion of the .EXE, as normally occurs. WarpLink's overlay manager will load overlays from the end of the .EXE file rather than a .OVL file. Technical Note When WarpLink is building the overlay file to place at the end of the .EXE file, the standard .OVL file is still created as a temporary file and it is later deleted by WarpLink when linking is complete. If you wish to keep a xe ".OVL file name".OVL file that corresponds to the .EXE file name from being overwritten while linking with overlays using the /oi option, you must also use the /on option to specify a different overlay file name. The name specified in the xe "Link options:/on"/on option will be used as the temporary file name. PRIVATE  /ol:count Overlay maximum load count. Syntax Count can range from 1 to 512. Description The xe "Link options:/ol"/ol option specifies the number of entries in an internal table used by the WarpLink xe "Overlay manager:Internal tables"overlay manager when loading and unloading overlays. Only overlays currently loaded into memory require an entry in this table. If too few entries are specified, the overlay manager may not be able to operate correctly, leading to erratic program operation or failure. The default value of 96 (same as /ol:96) is generous enough for almost all overlaid programs. If you will have more than 96 overlays loaded simultaneously in the overlay pool, you should increase this value. Do not change the /ol setting without good reason and an understanding of what you are doing. The default setting should be maintained in almost all cases. Technical Note The xe "Memory:Conserving"memory allocation size for the internal table specified by /ol is one paragraph (or sixteen bytes) multiplied by the count value. For example, a setting of /ol:100 consumes 1600 bytes of memory. You may conserve a small amount of memory by reducing the /ol setting below the default value of 96, however the savings are so small that doing so is not recommended except in extremely tight memory situations. If you do reduce the /ol value, you must use a value that is high enough to provide a table entry for all of the overlays that will ever be simultaneously loaded in the overlay pool, including inactive ones, plus one. PRIVATE  /on:name Overlay file name. Syntax Name is the name of the xe "Overlay file:Name"overlay file. Description The xe "Link options:/on"/on option allows you to change the name of the overlay file created by WarpLink. By default, the overlay file will be the same name as the executable .EXE file with the .OVL extension. This option allows you to have an overlay file with a different name than your .EXE file name. Name can be modified after linking with the WarpMod utility, as described in Chapter 8, WarpMod Utility. If you rename a program's overlay file without using the /on WarpLink option or WarpMod's ON option, the overlay manager will not be able to find the overlay file and will terminate in error. You should not rename the overlay file at the DOS prompt without using WarpMod to change the overlay file name setting. PRIVATE  /op:[-]size Overlay pool size in kilobytes. Use - to leave memory free. Syntax Size is the size of the overlay pool in kilobytes. It can range from 1 to 512. Description The xe "Link options:/op"/op option lets you control the amount of memory used for overlays. The section of memory in which overlay code is stored is known as the overlay pool. Memory for the overlay pool is allocated when the overlaid program begins running. Use /op to limit the amount of memory used for overlays or change the allocation method. The overlay pool is a key component of WarpLink. Overlaid routines are swapped in and out of this overlay pool only. A WarpLink linked program will not wildly grab any available memory. When the overlay pool area is full, overlays will be swapped out of the overlay pool until they are needed again. Use the minus sign to indicate all except size kilobytes will be used for the memory pool. For example, /op:100 means that all except 100K of system memory is available for overlays. Do not use the minus sign with Clipper and Clarion programs. Omitting the minus sign means that only the specified amount of memory (in K) will be used. For example, /op:48 means your program will reserve 48K of memory for the overlay pool at startup. All overlaid functions will be swapped in and out of the overlay pool. WarpLink uses a default value of -144 if the /op option is not specified, as if you had used the /op:144 setting. This value can be modified after linking by using the WarpMod utility as described in Chapter 8, WarpMod Utility. PRIVATE  /op:m Use overlay pool minimum required size. Description The xe "Link options:/op\:m"/op:m option is a variation of the /op option. /op:m automatically sets the size of the overlay pool to be the minimum size, as calculated by WarpLink during linking. This option takes the guesswork out of having to calculate the smallest possible overlay xe "Overlay:Pool size"pool size for your program. If the xe "Link options:/r"/r option is used along with /op:m, the minimum required overlay pool size will be calculated and assigned. (The calculation is roughly equivalent to two times the largest overlaid segment plus the second largest overlaid segment minus one.) Otherwise, the absolute minimum overlay pool size is used, that is, the size of the largest overlaid segment. All sizes are in kilobytes. The xe "Overlay pool:Size"overlay pool size value can be modified after linking by using the WarpMod utility, as described in Chapter 8, WarpMod Utility, should you feel that program operation speed is too slow when using overlays. Often a minor increase in pool size of 5K15K can provide dramatic speed increases in programs slowed by overlay use. PRIVATE  /orp Swap active overlays at runtime to EMS 4.0 expanded memory. Description The xe "Link options:/orp"/orp option allocates a 128K swap area in expanded memory and swaps active overlays out to it. The last swapped overlay has priority over earlier ones if more than 128K of active overlays are swapped-out. The 128K of xe "EMS:Allocation"EMS memory allocated for use by /orp is automatically freed at program termination. Because the /orp option swaps directly to lower memory from EMS and not through the EMS page frame, it requires xe "EMS:3.0"xe "EMS:4.0"EMS 4.0 -- not 3.0 -- compatibility. All machines with an 80386 or higher level chips supporting EMS should have this capability, but many 80286s and 8088s may not. It depends upon the EMS card or motherboard. The /orp option has lower priority than the xe "Link options:/ort"/ort option if both are specified. They cannot operate simultaneously. If you specify both the /ort and /orp options, XMS (/ort) active overlay swapping will be used unless 128K of free XMS is not available, at which time the WarpLink overlay manager will attempt to use 128K of EMS for swapping. You may wish to specify both options if your program will be operating on a mix of machines that may have either EMS or XMS memory. See Also Refer to the /ohp option for more information. Clipper User Note If you use the /orp option, the Clipper 5 debugger CLD.EXE will not function with your program. Use WarpMod to turn this option off and on quickly, if necessary. Clarion User Note The /orp option has no effect when used with xe "Clarion:/orp option"Clarion programs. Be sure to register your copy of WarpLink in order to keep up with future developments on this and other options. PRIVATE  /ort Swap active overlays at runtime to XMS extended memory. Description The xe "Link options:/ort"/ort option allocates a 128K swap area in extended memory and swaps active overlays out to it. The last swapped overlay has priority over earlier ones if more than 128K of active overlays are swapped-out. The 128K of xe "XMS:Allocation"XMS memory allocated for use by /ort is automatically freed at program termination. The /ort option has priority over the xe "Link options:/orp"/orp option if both are used -- they cannot operate simultaneously. If you specify both the /ort and /orp options, XMS (/ort) active overlay swapping will be used unless 128K of free XMS is not available, at which time the WarpLink overlay manager will attempt to use 128K of EMS for swapping. You may wish to specify both options if your program will be operating on a mix of machines that may have either XMS or EMS memory. See Also Refer to the /oht option for more information. Clipper User Note If you use the /ort option, the xe "Clipper 5 :CLD.EXE and options"Clipper 5 debugger CLD.EXE will not function with your program. Use WarpMod to turn this option off and on quickly, if necessary. Clarion User Note The /ort option has no effect when used with xe "Clarion:/ort option"Clarion programs. Be sure to register your copy of WarpLink in order to keep up with future developments on this and other options. PRIVATE  /os:size Overlay manager internal stack size in kilobytes. Syntax Size is the size of the internal stack in kilobytes. It can range from 1 to 63. Description The xe "Link options:/os"/os option specifies the size of the overlay manager internal stack used to store information about active, but swapped out, overlays. The default value of 2 (same as /os:2) is generous enough for almost all overlaid programs. Only if you have a program with deeply nested overlays and a small overlay pool relative to the overlays being loaded (and thus a great deal of swapping out of active overlays) may you need to increase the /os value. Each size increment is quite large (1K), so even if an increase above the default is necessary, usually a setting of /os:3 or /os:4 will suffice. Do not change the /os setting without good reason and an understanding of the implications for your program. The default setting should be maintained in almost all cases. Do not confuse the /os setting with the /st setting. The /st option specifies the size of your program's stack. If you receive a stack error message from your program related to stack size, you should modify the xe "Link options:/st"/st option setting rather than the /os option setting. Technical Notes The xe "Memory:Conserving"memory allocation size for the overlay manager internal stack specified by /os is one kilobyte times the count value. For example, a setting of /os:4 consumes 4096 bytes of memory. You may conserve an additional 1K of memory for your program by reducing the /os setting below the default value of 2 to a setting of 1 (/os:1). This reduction will slightly increase the chance of an overlay manager internal stack underflow error. If the xe "Overlay manager:Internal stack"overlay manager internal stack is set too low, a fatal overlay manager error will occur, the overlay manager will display error message feedback, and the program will terminate execution. Programs which inadvertently go into an infinite loop that causes active overlay swapout may cause a fatal overlay manager error to occur. For example, an overlay calls other overlays which in turn call other overlays which eventually call the first overlay without returning, restarting the infinite loop. The fatal overlay manager error may occur before other symptoms related to the infinite loop become apparent because the internal stack will eventually underflow as more and more active overlays are swapped out. Be aware of the potential for this situation as it indicates a problem in your program that needs correction. It is not a problem with the WarpLink overlay manager or an indication that you need to increase the /os value. PRIVATE  /ou Place overlay pool in upper memory block (UMB). Description This xe "Link options:/ou"option places the overlay pool in an Upper Memory Block, using the specified overlay pool size (/op). If there is not enough room or xe "DOS:And UMB"UMBs are not supported on the machine running the overlaid program, conventional memory will be used. All UMB memory allocated for use by /ou is automatically freed at program termination. If you have specified an overlay pool size with a minus '-' sign to leave a specified amount of memory free, the /ou option operates a bit differently since it is not allocating conventional memory. In these cases, the WarpLink overlay manager will allocate three times the largest overlay size for the overlay pool in upper memory. The /ou option has lower priority than the xe "Link options:/ox"/ox option if both are specified and enough free EMS is available to use the EMS page frame for the overlay pool. If you specify both the /ox and /ou options, upper memory blocks will only be used for the overlay pool if the /ox EMS test fails. You may wish to specify both options if your program will be operating on a mix of machines that may have either EMS or UMB memory. Whichever type of memory is available will be used for the overlay pool, with EMS tried first. Technical Notes xe "MS-DOS 5.0"xe "MS-DOS 5.0:And UMBs"MS-DOS 5.0 and above uses a different UMB allocation scheme than the xe "XMS:Allocation"XMS UMB-allocation standard when you use the command DOS=UMB in your CONFIG.SYS file. The WarpLink overlay manager will attempt to detect this and allocate xe "UMB:Allocation"a UMB for the overlay pool using the alternate MS-DOS scheme. If you experience problems using UMB's with MS-DOS 5.0 or above, try removing the DOS=UMB command in your CONFIG.SYS file. Free UMB space is not always contiguous. For example, your computer may have 100K of free UMB space, but it may be split up into two 50K blocks. If the overlay pool requires more than 50K in this situation, UMB's cannot be used and the overlay manager will place the overlay pool in conventional memory. Clipper 5 User Note If you use the /ou option, the xe "Clipper 5 :CLD.EXE and options"Clipper 5 debugger CLD.EXE will not function with your program. Use WarpMod to turn the option on and off quickly, if necessary. PRIVATE  /ox[:e-var] Place overlay pool in expanded memory (EMS) page frame.  Syntax [e-var] is the setting of an environment variable that tells WarpLink to use the EMS page frame ONLY if the listed environment variable is set to the specified value. The environment variable is case sensitive. That is, /ox:OVLEMS=on does not match SET OVLEMS=ON. DOS will always capitalize the environment variable (but not its setting). Therefore, using /ox with any lowercase environment variable will always cause the search to fail. In other words, /ox:ovlems=ON will not match SET ovlems=ON; use SET OVLEMS=ON. The search ends successfully when the target environment string is located. If the setting contains more characters than the option, the extras are ignored. For example, if you SET OVLEMS=ONRIGHTNOW, and use /ox:OVLEMS=ON, it will still match the OVLEMS environment variable. Description Using the xe "Link options:/ox"/ox option instructs the WarpLink overlay manager to automatically put the overlay pool into the expanded memory (EMS) page frame when the program runs. All EMS memory allocated for use by /ox is automatically freed at program termination. The optional parameter [e-var] allows use of an environment variable to trigger EMS overlay pool area use. For example, if you linked with /ox:OVLEMS=ON, the EMS page frame would be used only if you had SET OVLEMS=ON. Otherwise the overlay pool size loads in conventional or upper memory. You can use whatever environment names and settings you like. For example, /ox:COW=MOO is legitimate and will match SET COW=MOO. However, do not use blanks in the environment variable or setting. The environment variable and setting, including the equal sign (=), must not exceed 31 characters or you will get an invalid option error message. The /ox option supersedes the /op setting completely, placing a fixed 63K overlay pool in the EMS page frame. If insufficient or no EMS is present when the program starts up, then the overlay pool will be established in normal or upper memory with the pool size depending upon the size specified by the /op option. (If no xe "Link options:/op"/op option was used, the default value of 144 will be used.) This will be extremely helpful for programs that are running on a variety of platforms -- WarpLink can optimize the program depending on the memory configuration of each machine. Therefore, it is a good idea to use both the /ox and /op options if the program will be running on various machine configurations. If your program requires an overlay pool larger than 63K, do not use the /ox option. Use of the xe "EMS:Page frame"EMS page frame for the overlay pool prevents EMS 3.0 overlay file stashing via the /ohp3 and xe "Link options:/ohp"/ohp options. The /ox option automatically shuts off such stashing because EMS 3.0 routines must map into the EMS page frame that /ox uses to hold the overlay pool that the stashed overlay is being copied to. If you use /ohp and /ox, and the /ohp routines detect EMS 3.0 usage, then stashing an overlay file to EMS will be automatically shut off at runtime. Note that it is always safe to specify both the /ox and xe "Link options:/ohp3"/ohp options. If the WarpLink overlay manager detects EMS 4.0 support, then simultaneous use of the EMS page frame for the overlay pool and stashing of the overlays to EMS can occur. If it does not detect EMS 4.0 support, then only the EMS page frame for the overlay pool will be used. The /ox option has priority over the xe "Link options:/ou"/ou option if both are specified and enough free EMS is available to use the EMS page frame for the overlay pool. If you specify both the /ox and /ou options, Upper Memory Blocks will only be used for the overlay pool if the /ox EMS test fails. You may wish to specify both options if your program will be operating on a mix of machines that may have either EMS or UMB memory. Whichever type of memory is available will be used for the overlay pool, with EMS tried first. Version Note You do not need to use the xe "_OVLMGR_FREE_EMS"_OVLMGR_FREE_EMS or xe "_OM_FREE_EMS"_OM_FREE_EMS calls that were required by versions of WarpLink prior to 2.0 to free the EMS memory allocations made by the /ox option. Technical Notes Four xe "EMS:Compatibility"EMS pages (64K) are allocated when using /ox. If four free pages are not available, the WarpLink overlay manager will not use the EMS page frame for the overlay pool, placing it either in conventional memory or upper memory depending upon the /ou option setting. Some very early versions of xe "EMS:Allocation"EMS disk caches and memory resident programs are intolerant of sharing the EMS page frame because they do not save and restore the EMS page mapping while they operate in the background. These versions will conflict with placement of the overlay pool in the EMS page frame. If you have such a program, you should either get an updated version of the program that does not cause EMS page frame compatibility problems, or not use the /ox option. You may wish to use the environment variable capability of the /ox option if you are concerned about such programs. This will enable users to use the EMS page frame for the overlay pool only if they are certain that there will be no compatibility problems. Clipper User Note The /ox option requires using the xe "Clipper:BADCACHE setting"BADCACHE xe "Clipper:E0 setting"setting with Clipper 5 programs and turning off EMS use (SET CLIPPER=E0) with Clipper Summer '87 programs. If you use the /ox option, the xe "Clipper 5 :CLD.EXE and options"Clipper 5 debugger CLD.EXE will not function with your program. Use WarpMod to turn this option off and on quickly, if necessary. PRIVATE  /ql Perform QuickLinker link. Description This xe "Link options:/ql"option creates a file with the extension .QLK. The file contains information about the library modules linked into the program. The first use of /ql will create a xe ".QLK file".QLK file, causing a slightly slower link. Subsequent xe "QuickLinker option"links will use the existing .QLK file to locate needed library modules and should link faster. You can alternate linking with and without using /ql. The .QLK file will only be accessed (or created) when /ql is specified, otherwise the link proceeds normally. Use of /ql presumes that you will not change your libraries (count, order, and version) between links. Therefore, it is not recommended that you use /ql if you change libraries frequently. If you do change your library setup, delete the old .QLK file or else you may receive internal errors from WarpLink when using the /ql option as it tries to use old, invalid, library information. With xe "Direct library module specification"direct library module specification, the speed increase gained by using /ql can be simply breathtaking. Depending upon the number of libraries and modules specified, you may see the link speed increase up to three times the normal link speed. The more library modules specified, the greater the increase in speed by using /ql. Without direct library module specification, speed increases are more modest, typically 10%40% increase in link speed. Programs that use several large libraries will benefit the most from using the /ql option. If your program links in new library modules, your .QLK file will lose efficiency over time because it appends the new library module information at the end of the file, and causes more passes than a standard link. Also, old library modules that are no longer used will continue to be linked, causing increased xe "Memory:Conserving"memory overhead. To remedy either of these conditions, simply delete the .QLK file and use the /ql option to build a new file containing your new library use structure. .QLK files are deleted on linker error or Control-C exit if WarpLink is actively writing to them, rather than passively reading them. If you interrupt linking during the creation of a .QLK file so that it is not completely built, the .QLK file will be automatically deleted by WarpLink to prevent subsequent use of the incomplete .QLK file. Interruption during read access of a pre-existing .QLK file does not delete the .QLK file. If you use the /ql option with direct library module specification, you must place the option before the library list in the link file. If these options are not placed before the library list, you will receive internal errors due to irreversible processing of the library modules that requires those options not be altered after libraries are processed. For example, these options execute successfully: WARPLINK /QL /OP:M /R OBJMODULE,EXENAME,,LIB1:MOD1 LIB2 Do not place the /ql option after the library list as follows: WARPLINK /OP:M /R OBJMODULE,EXENAME,,LIB1:MOD1 LIB2 /QL If you xe "WarpLink:Internal errors"experience internal errors, unresolved external warning messages, or linking of unwanted library modules when using /ql, delete the old .QLK file and relink using the /ql option. PRIVATE  /r Reload active overlays swapped out upon return at same address. Description The xe "Link options:/r"/r option forces swapped out, but still active, overlays to be reloaded at the same address when the overlay which swapped them out returns. The /r option also allows an overlay calling the root, either directly or indirectly, to be safely swapped out by other overlays before the calling overlay is returned to. The reload overlay option is required for Clipper programs because xe "Clipper:Code as data"Clipper uses executable code as data and parses data tokens in the executable code segment. If an active overlay is swapped out and brought back in at a different address, Clipper may look at the original address where the routine was loaded for the next command and interpret whatever random values are there instead, with predictably poor results. Since reloading overlays at the same address typically forces more inactive overlays out of the overlay pool sooner, and requires a larger overlay pool for program operation, use of /r is not recommended if it is not necessary. Clarion User Note The /r option is turned on automatically by the xe "Link options:/cla"/cla option. You do not need to use /r with Clarion. Technical Note The /r option should also be used in the following situation: if a program performs indirect far calls (i.e. through a pointer) from an overlay to the root and there is a possibility that the root code will in turn call other overlays which cause swapout of the original xe "Root:Calling overlays"root-calling overlay. /r will keep the far address saved on the program stack as a valid return address. Otherwise, the original overlay that called the root and was then swapped out may reload in a different area of the overlay pool. This would cause program failure when the program attempts to return to the original overlay at the address saved on the stack. This is not a problem with near calls since the offset of the address saved on the stack is always correct. PRIVATE  /s Make symbol names case sensitive. Description Some languages, such as xe "Clipper:Symbol case"Clipper and xe "Clarion:Symbol case"Clarion, ignore the xe "Symbols:Case sensitive"case of symbols, variables, and procedure or function names. For example, the variables Count, COUNT, and count are treated as identical. Other languages, such as C, do not ignore the case of symbols. Given the previous example with these languages, Count, COUNT, and count would be treated as three separate variable declarations or definitions. If you receive xe "Warning:Externally declared symbol has no public definition"Externally declared symbol has no public definition warning feedback from WarpLink when using the xe "Link options:/s"/s option, and your program does not operate correctly, try linking without the /s option. Failing to use the /s option with languages that do not ignore the case of symbols can cause xe "Warning:Symbol has more than one public definition"Symbol has more than one public definition warnings from WarpLink if two variables or procedures differing only in case exist in the program. WarpLink will treat them as identical if the /s option is not used. PRIVATE  /sp Pack symbol table for Clipper code. Users Only Clipper programmers can use the /sp option. Description This option automatically packs the symbol table for Clipper Summer '87 and Clipper 5 code, thereby removing duplicate symbol table entries. This shrinks the size of your overlaid or nonoverlaid .EXE programs and frees memory for use by your program. Using /sp turns off the use of incremental linking. If both xe "Link options:/sp"/sp and /clpi are listed, the option specified last will be used. Linking with xe "Clipper:Symbol table compaction"symbol table compaction as specified by the xe "Memory:/sp affecting"/sp option uses more xe "Memory:Conserving"memory than linking without symbol table compaction. If you experience out of memory problems using the /sp option, you may have to free up memory by: removing device drivers or TSRs, changing or not using a make utility or using the stand-alone post-link symbol compaction utility, SP.EXE. PRIVATE  /st:size Set program stack size in bytes. Syntax Size is program stack size, in bytes. Description This xe "Link options:/st"option allows you to modify the linked program's stack size. It will override the default stack set by the programming language. It corresponds to the Microsoft Link option of the same name. This value can be modified after linking with the WarpMod utility as described in Chapter 8, WarpMod Utility. In most situations, the default value for the program xe "Stack:Size"stack size that is set by your compiler is sufficient. This value will seldom need to be modified, but this option is available for those situations where more stack space than the language default is needed. Do not confuse the /st setting with the xe "Link options:/os"/os setting. The /os option specifies the size of the overlay manager's internal stack. If you receive a stack error message from your program related to stack size, you should modify the /st option setting rather than the /os option setting. PRIVATE  /tf:name Set temporary file name. Syntax Name is the name of the desired temporary file. Full path and drive specification are optional. Description This xe "Link options:/tf"option allows you to specify the name of the temporary file to be created on disk. A xe "Temporary file:EMS"xe "Temporary file:XMS"temporary file is necessary during the link when the program image is too large to fit in conventional memory and cannot fit into EMS or XMS, or the /xp and /xt option is not used. This option can be very useful if the development machine uses RAM disks or multiple drives with differing disk access speeds, or if you wish to always use the same temporary file name. Technical Notes The default name of the xe "Temporary file:Naming"temporary file is VM.TMP in DOS versions prior to 3.0. In DOS 3.0 and later, it is a unique name. This file will be deleted upon linking completion. A pre-existing file with the same name as the temporary file name listed in the /tf option will be overwritten by the new temporary file. PRIVATE  /udl:name Use named D-format dynamic library at runtime. Syntax Name is the name of a .DDL file. Description The xe "Link options:/udl"/udl option supplies the names of support DDL files to the xe "DDLs:Master"master DDL file being created. Each file may already exist, or it may be created in the future. The file's presence is not required until your program using dynamic libraries begins to execute. This allows you to create and modify DDL files in any order you choose. Up to fifteen separate support DDL file names may be supplied to a master DDL file. Each DDL file supplied must be preceded by the udl: text. The /udl option only supports one file name each time it is used. See Also Refer to Chapter 17, Using D-format Dynamic Libraries, for more information on using D-format dynamic libraries. Technical Note DDL xe "DDLs:Support files"support files may not be nested. If a support DDL file for a program has support DDL files in turn, those support DDL files will not be linked into the program. All support DDL files for the master DDL file must be listed when creating the master DDL file. PRIVATE  /w0 Set warning exit code to 0, instead of 1. Description Use this xe "Link options:/w0"option to set the DOS ERRORLEVEL, or xe "DOS:Return code"return code, to 0 when warning messages are encountered. When using some MAKE utilities, having a DOS xe "DOS:ERRORLEVEL"ERRORLEVEL greater than zero will cause the MAKE file to stop with an error. The /w0 option allows you to override WarpLink's default ERRORLEVEL of 1 for warnings so that your MAKE file can operate properly. Fatal errors will continue to return ERRORLEVEL codes of 2 and above. PRIVATE  /wn Do not display warnings. Description The xe "Link options:/wn"/wn option will inhibit any xe "Warnings:Displaying"warning messages normally displayed by WarpLink. The circumstances that cause the warning will still be present, but WarpLink will not notify you that they exist. This option can be useful if you believe that the warning messages being received are benign and no longer wish WarpLink to display them. Fatal error messages are not affected by this option and will be displayed by WarpLink. PRIVATE  /xp Use expanded memory (EMS) during link. Description The xe "Link options:/xp"/xp option stashes the overlay file and the temporary file (if any) as well as object modules in expanded memory at linktime, assuming an EMS driver is present. This will speed up the link process considerably. WarpLink uses the stash order for the /xp option that is consistent with link speed priority. Stashing the xe "Overlay file :Link stash"overlay file typically speeds link times more than stashing the xe "Temporary file :Link stash"temporary file and takes precedence if both will not fit into extended memory. In turn, stashing the temporary file has precedence over stashing the object modules. If the overlay file will not fit into extended memory, but the temporary file will, then the temporary file will be stashed. If you have a dual XMS and xe "EMS:Linktime use"EMS driver, such as xe "QEMM"QEMM or xe "386^Max"386^Max, you may want to choose the xe "Link options:/xt"/xt option instead of the /xp option in lower free EMS/XMS memory circumstances. Since /xp starts by stashing object modules, it may run out of free EMS before the temporary file is stashed. WarpLink then removes stashed object modules -- resulting in a slight speed degradation -- because stashing the temporary file provides better overall link performance than stashing object modules. Since the /xt option only stashes the temporary and overlay file, it applies all free memory to that task. Also, extended memory is often slightly faster to access than expanded memory. Of course, if you do have enough EMS to stash object modules and the temporary file, using the /xp option will always be faster than the /xt option. It is possible to use both the xe "Link options:/xp"/xp and xe "Link options:/xt"/xt options simultaneously, with WarpLink giving preference for stashing the temporary and overlay file to XMS. Remember that if you have a dual EMS/XMS driver, WarpLink uses all free memory through the /xp option and leaves no free memory for the /xt option, effectively negating its use. You need separate EMS and XMS allocations to use both the /xp and /xt options effectively. PRIVATE Memory ConfigurationUse the /xp option?Use the /xt option?EMS OnlyYesNoXMS OnlyNoYesEMS and XMSYesYesEMS or XMSNoYes Technical Note You can use both /xp and /xt options simultaneously by using a dual xe "EMS"EMS and xe "XMS:Linktime use"xe "XMS"XMS driver (such as xe "QEMM"QEMM or xe "386^Max"386^Max). However, it is recommended that the /xt option be used alone, because it is usually slightly faster. PRIVATE  /xt Use extended memory (XMS) during link. Description The xe "Link options:/xt"/xt option stashes the xe "Overlay file :Link stash"overlay file and the xe "Temporary file :Link stash"temporary file (if any) in extended memory at linktime, assuming an XMS driver is present. This will speed up link time significantly. WarpLink uses the stash order for the /xt option that is consistent with link speed priority. Stashing the overlay file typically speeds link times more than stashing the temporary file and takes precedence if both will not fit into extended memory. If the overlay file will not fit intoextended memory, but the temporary file will, then the temporary file will be stashed. If you have a dual XMS and EMS driver, such as xe "QEMM"QEMM or xe "386^Max"386^Max, you should select the /xt option instead of the /xp option in lower free EMS/XMS memory circumstances. This makes the most efficient use of your memory configuration. It is possible to use both the xe "Link options:/xp"/xp and /xt options simultaneously, with WarpLink giving preference for stashing the temporary and overlay file to XMS. Be cautioned that if you have a dual EMS/XMS driver, WarpLink will take all free memory through the /xp option and leave no free memory to the /xt option, effectively negating its use. You need separate xe "EMS"EMS and xe "XMS"XMS allocations to use both the /xp and /xt options to any effect for the /xt option. PRIVATE Memory ConfigurationUse the /xp option?Use the /xt option?EMS OnlyYesNoXMS OnlyNoYesEMS and XMSYesYesEMS or XMSNoYes Technical Note You can use both /xp and /xt options simultaneously by using a dual EMS and XMS driver (such as QEMM or 386^Max). However, it is recommended that the /xt option be used alone, because it is usually slightly faster. PRIVATE Chapter 7. tc \l 1 "Chapter 7. " Using WarpLink with Clarion 2.1  When using xe "Clarion 2.1"Clarion 2.1, the WarpLink overlay manager automatically creates a xe "Clarion:Swap file "swap file on disk during overlaid program operation. This swap file keeps swapped-out but still active overlay data from being reinitialized. The swap file holds data from active overlays while they are swapped-out. When the active overlay is swapped-in again, data is read back in from the swap file. The swap file also saves overlay information while another program is run from the overlaid Clarion program and restores it when the run is complete. Swap Files The default swap file name is OVL_SWAP.$01. If the file OVL_SWAP.$01 is already in use, then the file OVL_SWAP.$02 is used. In a similar manner, if OVL_SWAP.$02 already exists, then OVL_SWAP.$03 is created. The overlay manager continues to look for an unused file name in sequence, up to OVL_SWAP.$99. The overlay manager will terminate in failure after unsuccessfully attempting to use the final file name, OVL_SWAP.$99. WarpLink-overlaid Clarion programs can run other WarpLink-overlaid Clarion programs by using distinct swap file names. If the swap file names were not distinct, then the program that was run would overwrite the old swap file and cause the original program to fail upon return. The WarpLink overlay manager automatically deletes these swap files upon program termination so that old swap files do not use up disk space. If WarpLink does not delete a swap file due to improper program termination (such as rebooting the computer prior to exiting the program or after loss of power), you should delete the swap file from DOS. These deletions will free up disk space and speed up the overlay manager's task of finding a unique swap file name. Changing the Swap File Name The base name xe "Clarion:OVL_SWAP"xe "OVL_SWAP:Environment variable"OVL_SWAP, but not the extension, can be changed by setting the environment variable OVL_SWAP to a valid file name, including any drive and path specification. This feature is particularly useful for networks, where many people can be running the same overlaid Clarion program. If the environment variable OVL_SWAP exists, but points to an invalid file name (e.g. a nonexistent directory), the default swap file base name OVL_SWAP is used. Through use of the swap file, Clarion users can safely use the /op:m setting to keep program memory requirements to a minimum. Using IDLE Procedures Do not xe "Clarion:Overlay IDLE procedures"overlay IDLE procedures. Although they will overlay without error messages from WarpLink, they cannot be marked as inactive by the overlay manager when they finish execution. This overloads the overlay pool, forcing more active overlay swap-outs and hurting program performance, probably significantly. The problem increases each time the overlaid IDLE procedure is called and eventually leads to program failure. Using Options All runtime EMS and XMS options work correctly with WarpLink and Clarion 2.1 except that the /orp and /ort options have no effect due to the swap file. Remember to use the /cla option and the xe "Clarion:Profiler"xe "Clarion:Overlaying"Clarion overlay manager, CNOVLMGR.OBJ, when using Clarion 2.1 with overlays. Also, when profiling your code with the WarpSpeed profiler, use the CNWSPRUN.EXE file rather than WSPRUN.EXE. WSPSTAT.EXE, the companion profiler, operates correctly with both Clarion as well as other languages. Overlaying Clarion Modules Do not overlay the Clarion CLARION.OBJ and CLARIONO.OBJ modules. You cannot overlay .BIN modules since they do not contain Clarion code. Also do not overlay the main Clarion program object module. All other Clarion object modules may be overlaid. Do not attempt to overlay the Clarion libraries, CLARION1.LIB and CLARION2.LIB. They do not contain xe "Clarion:Using EMS"xe "Clarion:Using XMS"Clarion code and cannot be overlaid when Clarion code is being overlaid through the /cla option. See Also Refer to Chapter 19, Using Overlay Pool Sizes Below Minimum Required. PRIVATE Chapter 8. tc \l 1 "Chapter 8. " WarpMod Utility  The xe "WarpMod"WarpMod utility allows quick and easy fine-tuning of overlaid or nonoverlaid .EXE programs (that were created with WarpLink) without re-linking. This is especially helpful when adjustments must be made while running a program at a location other than your development machine. WarpMod Format WarpMod is very simple to use, and employs a command syntax very similar to WarpLink. WARPMOD [program file] [command options] Using WarpMod WarpMod will prompt you for the program file name if none is supplied. Modifiable environmental and overlay manager parameters from the target file are displayed and may be modified. In addition, your program's original date and time-stamp may be preserved, even if you modify the program settings. While running WarpMod, overlay manager options will only be displayed if WarpMod detects that overlays were used in the program. WarpMod will only display and allow modification of the /as and /st options for nonoverlaid programs. WarpMod allows you to make interactive changes and supports quick keys and cursor movement keys. WarpMod highlights the field to be modified and displays a one-line description of the option selected at the bottom of the screen. Press [ENTER] to enter a new value for the option. Press [F10] to restore all modified options to their original values. WarpMod also accepts command line arguments, bypassing interactive mode to allow batch or simple changes. You can precede an option with slash (/) or minus (-) sign or forego these symbols. Use a trailing plus (+) sign to turn on an option. Use a trailing minus (-) sign to turn off an option. Do not change the /ol or /os settings unless you are absolutely sure of the need to modify them. The default settings should be maintained in almost all cases. WarpMod Example WARPMOD PROGRAM.EXE -D OP:32 /ORT- ORP+ /OX:A=B ST:3334 -OHP:0 OU OHT:512 In the example above, WarpMod: ( Preserves the original date of the EXE file, ( Gives an overlay pool size of 32K, ( Turns off the /ort option, ( Turns on the /orp option, ( Turns on the /ox option with environment variable A=B ( Sets the stack to 3334 bytes, ( Turns off the /ohp option, ( Turns on the /ou option, and ( Turns on the /oht option with a value of 512 WarpMod also supports a /mono option. Use /mono to allow use of WarpMod with xe "WarpMod:Monochrome monitors"monochrome monitors. xe "WarpMod:Distribution"Distribution Note Unlike the other WarpLink utilities and files, WarpMod may be freely distributed to others in order to allow them to make their own modifications "in the field." Technical Note Do not use WarpMod on WARPMOD.EXE. The overlay file signature is contained in WarpMod even though WarpMod is not overlaid. Using WarpMod on itself will confuse the WarpMod program. PRIVATE Chapter 9. tc \l 1 "Chapter 9. " WarpSpeed Profiler  xe "WarpSpeed Profiler"WarpSpeed is a program profiler that allows you to analyze your program for maximum efficiency and effectiveness. WarpSpeed provides detailed information about your program because its granularity is at the function level. WarpSpeed provides the following information about your program: ( Total execution time ( Time spent in DOS or BIOS calls ( Time spent in the overlay manager ( Time lost to the profiler ( Number of calls to both overlaid and nonoverlaid functions ( Number of overlay loads ( Number of overlay reloads ( Average times for individual functions ( Cumulative times for individual functions You can use WarpSpeed profile information to improve the efficiency of your programs by optimizing your code structure. For example, if you have a function in the root that is seldom called, putting that function in the overlay could save memory without affecting program speed. A function that takes a lot of time to execute could indicate that the function contains some inefficient code that can be optimized. In either case, running WarpSpeed again after making a change will show you how the change affected the execution of your program. A big advantage of using WarpSpeed over many other profilers is that you do not have to change your program to run WarpSpeed. All of the information gathering and statistic gathering activities occur outside of your program. This means that you do not have extra profiling code within your program. In addition, you can profile a part of your program as easily as the entire program. WarpSpeed Function Overview WarpSpeed consists of two executable files that are included with the WarpLink package: WSPRUN.EXE and WSPSTAT.EXE. (xe "Clarion:Profiler"xe "Clarion:Profiler"Clarion users should use CNWSPRUN.EXE instead of WSPRUN.EXE.) xe "WSPRUN:Using"WSPRUN is the analyzing portion of the profiler. It generates a .WSP file from the map file created by WarpLink, then runs your program, and collects statistics on it as the program runs. When the program exits, WSPRUN writes statistics out to the same xe ".WSP file".WSP file. For each individual function within a program, WSPRUN collects: ( Number of times the function is called. ( Time spent executing the function. ( Time spent executing the function and all lower-level functions that it calls (cumulative time). WSPSTAT generates a report from the statistics collected by WSPRUN. By default, this output goes to a file with the same name as the .WSP file, but uses the extension .WSS. You can specify a file name or send it to standard output so it can be piped into other programs. WSPSTAT reports the number of calls and execution time for each function by default. You can specify additional information with command line options. Using WarpSpeed To profile your program, follow these steps: 1. Link with the /mx command option of WarpLink to generate an expanded map file. 2. Run WSPRUN.EXE with appropriate arguments and the name of your program to generate a data file with the extension .WSP. 3. Run WSPSTAT.EXE with the .WSP file name to generate a report file with the .WSS extension. (Or, WSPSTAT can generate a .DBF file, if desired.) You can review the .WSS (or .DBF) file, make changes to the code or program structure, recompile, and run the profiler again. It's that simple. WSPRUN Format WSPRUN [options] RUNFILE[.exe] [arguments...] All options must precede the file name. The square xe "Brackets"brackets ([ ]) indicate an item is optional. Do not use the brackets. Italics indicate an item is replaced with a user-defined value or option. Options refer to the WSPRUN options described below. Runfile is the name of the executable file to be profiled. Arguments refer to any command line argument(s) runfile requires in order to execute properly. They are passed directed to runfile as if it was executed from the DOS prompt. xe "WSPRUN:Options summary"WSPRUN xe "Options:WSPRUN"Options Summary PRIVATE OptionDescription/a:sizeSpecify activation stack size./if:file Include symbols in file. (Wildcards are permitted.)/im:moduleInclude symbols in module. (Wildcards are permitted.)/is:symbolInclude symbol. (Wildcards are permitted.)/lInclude all libraries./m:mapfileOverride map file name./nInclude segment name symbols./oCollect overlay statistics only./sMake symbol names case-sensitive./uTrim leading underscore from symbol names./w:wspfileOverride .WSP file name/xf:fileExclude symbols in file. (Wildcards are permitted.)/xm:moduleExclude symbols in module. (Wildcards are permitted.)/xs:symbolExclude symbol. (Wildcards are permitted.)/yAllows out-of-date map file. WSPRUN Options Details PRIVATE  /a:size Specify activation stack size. Syntax Size is the size of the profiler activation stack in records. Each record is 18 bytes. The default is 100 records. Description This xe "WSPRUN options:/a"option sets the size of the activation stack. This is a stack that the profiler uses to keep track of active functions. PRIVATE  /if:file Include symbols in file. (Wildcards are permitted.) /im:module Include symbols in module. (Wildcards are permitted.) /is:symbol Include symbol. (Wildcards are permitted.) Syntax You can use * and ? wildcards to indicate a string in the file or module name. However, * differs from the familiar DOS wildcard in that it means any string of characters (including empty strings). You can use multiple wildcards within one name. Description This xe "WSPRUN options:/if"xe "WSPRUN options:/im"xe "WSPRUN options:/is"option includes symbols in a named file or module or includes all named symbols. By default, WarpSpeed only profiles functions defined in modules not included in libraries. You can use as many of these switches as desired on the command line. They are processed from left to right so that the later ones override earlier ones. Examples To profile MYPROG.EXE including all symbols in EXTEND.LIB except for DBEDIT(), use: /IF:EXTEND.LIB /XSS:DEBEDIT MYPROGRAM To include all symbols defined in any library file, use: /IF:*.LIB To include any library file with x within its name, use: /IF:*X*.LIB PRIVATE  /l Include all libraries. Description This xe "WSPRUN options:/l"option include all libraries during WSPRUN. The default is not to profile any function in a library. (Achieve the same results by using the option: /IF:*.LIB.) PRIVATE  /m:mapfile Override map file name. Syntax Mapfile is the name of the .MAP file. Description This xe "WSPRUN options:/m"option overrides map file name so you can use a different name. By default, WarpSpeed uses the file name that matches the executable file but changes the extension to .MAP. PRIVATE  /n Include segment name symbols. Description This xe "WSPRUN options:/n"option includes segment name symbols in the profile statistics. It is required for profiling Clipper 5 programs if STATIC functions are to be profiled. PRIVATE  /o Collect overlay statistics only. Description This xe "WSPRUN options:/o"option inhibits collection of nonoverlay statistics. Use /o to limit the scope of the profiler to include overlay load and reload information only. PRIVATE  /s Make symbol names case-sensitive. Description This xe "WSPRUN options:/s"option makes symbol names case-sensitive to the profiler. For example, _HELP and _help indicate two different symbols when using the /s option. PRIVATE  /u Trim leading underscore from symbol names. Description This xe "WSPRUN options:/u"option removes one leading underscore from the name of each symbol that starts with an underscore. C programmers may find this option especially useful if their compiler automatically places a leading underscore on function names. Many C compilers do add the underscore. PRIVATE  /w:wspfile Override .WSP file name Syntax Wspfile is the name of the desired file. Description This xe "WSPRUN options:/w"option overrides the name of the .WSP file. By default, WSPRUN creates a file with the same name as the map file but using a .WSP extension. PRIVATE  /xf:file Exclude symbols in file. (Wildcards are permitted.) /xm:module Exclude symbols in module. (Wildcards are permitted.) /xs:symbol Exclude symbol. (Wildcards are permitted.) Syntax You can use * and ? wildcards to indicate a string in the file or module name. However, * differs from the familiar DOS wildcard in that it means any string of characters (including empty strings). You can use multiple wildcards within one name. Description This xe "WSPRUN options:/xf"xe "WSPRUN options:/xm"xe "WSPRUN options:/xs"option excludes symbols in a named file or module, or all named symbols. By default, WarpSpeed only profiles functions defined in object modules not included in libraries. You can use as many of these switches as desired on the command line. They are processed from left to right so that the later ones override earlier ones. Examples To profile MYPROG.EXE including all symbols in EXTEND.LIB except for DBEDIT(), use: /IF:EXTEND.LIB /XSS:DEBEDIT MYPROGRAM To exclude any symbols starting with _ use: /XS:_* To exclude any symbol ending with @, use: /XS:*@ Technical Note If you specify xe "WSPRUN options:/u"/u and one of these options, the exclude switch only matches names starting with more than one underscore (_). PRIVATE  /y Description This xe "WSPRUN options:/y"option allows use of an out-of-date map file. WSPRUN generates a warning message if the map file is older that the executable file. This switch overrides the warning and the program automatically proceeds. WSPSTAT Format WSPSTAT [options] WSPFILE[.WSP] [OUTPUT [.WSS]] All options must precede the file name. The square xe "Brackets"brackets ([ ]) indicate an item is optional. Do not use the brackets. Italics indicate an item is replaced with a user-defined value or option. Options refer to the WSPSTAT options described below. WSPFILE is the name of the .WSP file created by WSPRUN. output is the name of the file created by WSPSTAT. The default extension is xe "File extensions:.WSS"xe ".WSS file".WSS, however WarpSpeed can create a xe ".DBF file ".DBF file instead. xe "WSPSTAT options summary"xe "WSPSTAT:Options summary"WSPSTAT xe "Options:WSPSTAT"Options Summary PRIVATE OptionDescription/aReport average times./cDirects output to console (standard output)./dDirects output to .DBF file./lm:marginSet report left margin. /mInclude module names./n:widthSet width of NAME column. /oOverlay statistics only./pReport percentages of run time./pl:lengthSet report page length. /saSort by average times./scSort by numbers of calls./suSort by cumulative times./tCollect timing statistics only./uReport cumulative times./zInclude never-called functions. WSPSTAT Options Details PRIVATE  /a Report average times. Description This xe "WSPSTAT options:/a"option reports average time (seconds) per function call. The average time is the total function time divided by the number of calls to that function. PRIVATE  /c Directs output to console (standard output). Description This xe "WSPSTAT options:/c"option directs WSPSTAT output to the console (standard output) instead of a file. When this option is used, a xe "File extensions:.WSS".WSS (or xe "File extensions:.DBF".DBF) file is not created. Instead, the results are routed to the standard output device. PRIVATE  /d Directs output to .DBF file. Description This xe "WSPSTAT options:/d"option directs output to a xe ".DBF file".DBF file. /d generates a Clipper or dBASE compatible file instead of xe "File extensions:.WSS".WSS file. Each record contains the following fields: PRIVATE FieldTypeSize/FormatNAMECharacter16MODULECharacter12RECTYPECharacter 1NCALLSNumeric 8.0FCNTIMENumeric10.3CUMTIMENumeric10.3 The size of the NAME field is set by using the /n option. RECTYPE is blank for normal records except for the first five records in the .DBF file. The values for NAME and RECTYPE for the first five records are: PRIVATE NameRECTYPEElapsed timeERun timeRProfiler timePDOS/BIOS timeDOverlay ManagerO For the first five records, FCNTIME and CUMTIME both contain the appropriate time value. For the Overlay Manager record, NCALLS contains the number of overlaid function calls. PRIVATE  /lm:margin Set report left margin.  Syntax Margin is the size of the left margin in characters. The default is zero. The range is 0 to 80. Description This xe "WSPSTAT options:/lm"option sets the left margin of the report. Top and bottom margins are fixed at one line each. The right margin is not adjustable. WSPSTAT assumes that the destination printer is wide enough to contain all of the data. PRIVATE  /m Include module names. Description This xe "WSPSTAT options:/m"option includes module names for the profiler report. The module names are used for Clipper version 5 if STATIC functions were profiled, using the /n option of WSPRUN. PRIVATE  /n:width Set width of NAME column. Syntax Width is a number. The default width is 16. The range is 4 to 128. Description This xe "WSPSTAT options:/n"option sets the width of the NAME column in the .DBF file created by WSPSTAT. You must use /n with the /d option. PRIVATE  /o Overlay statistics only. Description This xe "WSPSTAT options:/o"option includes overlay statistics for WSPSTAT. It does not include the timing table. PRIVATE  /p Report percentages of run time. Description This xe "WSPSTAT options:/p"option reports a percentage of the runtime (seconds) for each function. PRIVATE  /pl:length Set report page length.  Syntax Length is a number. The default is 66 lines. Allowable lengths are 0 or any number greater than or equal to 10. Description This xe "WSPSTAT options:/pl"option sets the report page length for the output file. PRIVATE  /sa Sort by average times. /sc Sort by numbers of calls. /su Sort by cumulative times. Description These xe "WSPSTAT options:/sa"xe "WSPSTAT options:/sc"xe "WSPSTAT options:/su"options sort the output in descending order by: average time (/sa), number of calls (/sc), or cumulative time (/su). The default is to sort by function time. PRIVATE  xe "WSPSTAT options:/t"/t Collect timing statistics only. Description This xe "WSPSTAT options:/o"option includes the timing statistics for WSPSTAT. It does not include the load/reload table. PRIVATE  xe "WSPSTAT options:/u"/u Report cumulative times. Description This xe "WSPSTAT options:/p"option reports cumulative times for each function. PRIVATE  xe "WSPSTAT options:/z"/z Include never-called functions. Description This option directs WPSTAT's report to include functions that were never called. Additional Technical Information Your program will run slower under the xe "Profiler:Speed"xe "Profiler:Memory use"profiler. The speed loss depends upon which functions you choose to profile and can range from imperceptibly small up to a factor of 20 or more. The profiler also requires some memory: about 4K plus the size of your environment plus 18 bytes for each activation record, plus 15 bytes for each function profiled. File names and module names are taken from the Detailed Segment Map within the map file. Any drive or path specifications are stripped off both. All string matches are not case-sensitive. Do not profile a hardware xe "Profiler:Interrupt handler "interrupt handler or any function called by a hardware interrupt handler (including the timer tick). Be very careful about including libraries unless you are sure they do not use hardware interrupt handlers. You should not profile xe "Profiler:Self-modifying code"self-modifying code. Some floating point emulation libraries (such as EMU.LIB from Borland C/C++) use self-modifying code and errors will occur if you try to profile these libraries. xe "WSPRUN:Error messages"WSPRUN Feedback and Error xe "Error:Messages"Messages Incompatible overlay manager The program was linked with the wrong version of the WarpLink overlay manager. Relink with WarpLink 2.6+. Internal error: Activation stack overflow The activation stack size of XX was too small. Try again with a larger stack using the /a command line switch. This message indicates an error with the stack size. XX is the current activation stack size. The default is 100. Internal error: Unexpected breakpoint The profiler encountered a breakpoint (INT 3) instruction at location XXXX:XXXX (program loaded at segment XXXX) and could not identify the source of the breakpoint. Check your code for INT 3 instructions. Most internal errors which do not lock up the machine will produce this message. It may indicate code that cannot be profiled (e.g., self-modifying code, hardware interrupt handlers) or an invalid map file. The XXXXs are hexadecimal values which may help you track the problem. Invalid switch: should be /if, /im, or /is Invalid switch: should be /xf, /xm, or /xs The /i or /x option was not followed by f, m, or s. Correct your WSPRUN command line and try again. Missing activation stack size The /a option was not followed by a number. Correct your WSPRUN command line and try again. Missing map file name The /m option was not followed by a map file name. Missing name following /i? Missing name following /x? ? stands for f, m, or s. The message indicates /i? or /x? was not followed by a file, module or symbol name. Correct the WSPRUN command line and try again. Missing .WSP file name The /w option was not followed by a .WSP file name. Out of memory Either not enough memory is available to load the .WSP file or the statistics part of .WSP file will not fit into 65K memory. Unload any unnecessary TSRs and try again. Program terminated, exit code = XX XX, a decimal number, is the program's exit code. Codes 0 through 255 are normal exits. 0 usually means normal termination. Some programs will just return a random number. Code 256 means the program was terminated by pressing CTRL-C. 512 means the program aborted from a critical error (e.g. Abort, Retry, Ignore?). 768 to 1023 mean the program terminated and stayed resident. Do not profile a TSR. Too many code segments in map file The map file contained more than the WSPRUN limit of about 3,000 code segments. Too many module records This situation is highly unlikely. Please call technical support if you receive this message. Too many symbols in map file. The map file contained more than the WSPRUN limit of about 4,000 symbols. Unknown switch /? ? stands for a character. Refer to the WSPRUN Option Summary within this chapter for a list of permissible values. Warning: Executable file is newer than the map file Continue Y/N ? The time-stamp on the map file does not match the time-stamp on the executable file. If the executable file has been relinked without a map file and you used the old map file, you should not continue until you can use a new map file. If the map file is correct but the executable file has been changed with WarpMod, you should continue. Or, you could use the /y command-line option to automatically bypass the question as if you had pressed Y. The default is N, which will halt WSPRUN. File name: DOS error message Can't create file name: DOS error message Can't open file name: DOS error message Can't read file name: DOS error message Can't write file name: DOS error message Can't load file name: DOS error message These messages indicate a DOS error has occurred, e.g., file not found, path not found, access denied, or insufficient memory. Check the status of the file (listed in file name) and try again. File name is not a valid WarpLink expanded map file The file specified by file name was not produced by using WarpLink with /mx option or it has been damaged. Relink with WarpLink using the /mx option and then run WSPRUN again. File name:invalid This message indicates a .WSP file is invalid or corrupted. Please contact WarpLink technical support if you receive this message. File name:wrong file version This message indicates a .WSP file header has the wrong version number. Please contact WarpLink technical support if you receive this message. xe "WSPSTAT:Error messages"WSPSTAT Error xe "Error:Messages"Messages Invalid left margin The number following /lm must be 0 to 80. Invalid page length The number following /pl must be either 0 or >=10. Invalid switch: should be /lm The /l option must be followed by m. Invalid switch: should be /sa, /sc, or /su The /s option must be followed by a, c, or u. Missing left margin The /lm option must be followed by a number. Missing page length The /pl option must be followed by a number. Missing symbol name width The /n option must be followed by a number. No timing data in file WSPRUN aborted with an error. It did not update the .WSP file and so there are no statistics to report. Symbol name width too small (minimum 4) Symbol name width too large (maximum 128) The number following the /n option must be within acceptable limits, 4-128. Unknown switch /? ? stands for a character. This message indicates use of an illegal option. Refer to the WSPSTAT Options Summary within this chapter for a list of permissible values. File name: DOS error message Can't create file name: DOS error message Can't open file name: DOS error message Can't read file name: DOS error message Can't write file name: DOS error message Can't load file name: DOS error message These message indicate a DOS error has occurred, e.g., file not found, path not found, access denied, or insufficient memory. Check the status of the file (listed in file name) and try again. File name: Incompatible file format This message indicates a .WSP file was produced by the wrong version of WSPRUN. Verify that you have the latest version of WSPRUN and try again. File name: Invalid format This message indicates that a .WSP file is invalid or corrupted. Rerun WSPRUN and try again. PRIVATE Chapter 10. tc \l 1 "Chapter 10. " xe "Interactive WarpLink "Interactive WarpLink Utility  Interactive xe "WarpLink:Interactive"WarpLink is a front-end, "windowed," user interface for WarpLink. It is a heavily modified and debugged version of the D-Flat Version 6 program, as published in Dr. Dobb's Journal magazine by Al Stevens. Using Interactive WarpLink is similar to using other windowed user interfaces. If a mouse is detected, it will be enabled automatically. In addition to the interactive linking ability, you may also use Interactive WarpLink to build link files for you automatically. Interactive WarpLink Format Start Interactive WarpLink at the DOS prompt by entering: IW [project_file_name] Using Interactive WarpLink Four windows are visible upon startup. The left-most window (#1) contains the object modules to be linked. The next window to the right (#2) contains libraries. Note that it is not necessary to use plus (+) signs at the ends of lines in either window. Interactive WarpLink will perform most housekeeping chores for you, including adding plus signs where needed. The window farthest to the right (#3) contains link options. Set or reset various link options in this window by using the cursor keys (or mouse) to select an option and then pressing the Spacebar. Interactive WarpLink prompts you for additional settings with some link options. Two link options have optional settings: /CLP5 and /OX. Other options have required settings. All additional settings are retained once the corresponding options are turned off. In the Link Options window, you may explicitly set the .EXE (or .COM) and .MAP filename. The window near the bottom of the screen, Link File Name (#4), contains the default link file name to which you save changes. A fifth window only appears after you link using Interactive WarpLink. It will show any errors or warnings that occur during the link. Following a link without errors, you will see an Information Box that states no errors were found. Although the Error Log window (#5) is always present, it is not usually visible because the other four windows cover it. To restore any of the windows that are not (fully) visible, use the drop-down menus or the shortcut keys. The window shortcut keys are ALT1, ALT2, ALT3, ALT4, and ALT5. (The number corresponds to the window number.) To move or size the Interactive WarpLink environment, select the symbol of three lines (at the top left corner of the screen) by using the mouse or ALT '-'. Drop-down Menus Use the mouse, cursor control keys and xe "Shortcut keys"shortcut keys (shown in parentheses) to select options on the five drop-down xe "Menu:Drop-down"menus. The File xe "Menu:File"menu (ALT-F) contains six options: Load Select this option, (F3), to load and process a link file. Object modules, libraries, and link options automatically appear within the corresponding window. You can load more than one link file if desired. Subsequent link file loads are appended to pre-existing settings and text. New Select this option to reset and remove the object modules and libraries listed within the corresponding windows. Save Select this option (F2) to save the object modules, libraries and options settings to the link file specified in the Link File Name window automatically. If there is no link file specified, Interactive WarpLink will prompt you for a name. Save As Select this option to have Interactive WarpLink prompt you for a link file name and then execute the Save option (above). DOS Shell Select this option (ALT-D) to shell out to DOS. A memory image is written to disk in a temporary file. Type EXIT at the DOS prompt to return to Interactive WarpLink. The memory image is reloaded from the temporary file and the file is deleted. Exit Select this option (ALT-X) to exit back to DOS. This does not execute a DOS shell. You will leave Interactive WarpLink permanently. The Edit xe "Menu:Edit"menu (ALT-E) contains six options: Object Files Select this option (ALT1) to activate the Object Files window. Libraries Select this option (ALT2) to activate the Library window. Options Select this option (ALT3) to activate the Link Options window. Link File Select this option (ALT4) to activate the Link File Name window. Reformat Select this option (F4) to clean up the object module and library list. The reformatting is performed automatically when saving a link file (F2) from the File menu. Error Log Select this option (ALT5) to display the Error Log, a list of warnings or errors that occurred during the last link. The Link xe "Menu:Link"menu (ALT-L) contains one option: Link Select this option (F7) to shell to DOS and attempt to link using the current settings. Note that two temporary files, IWTEMP.$$$ and IWTEMP2.$$$, are created or overwritten during this linking process. They can be safely deleted when the link is completed. This option does not save to the current Link File Name, shown in Window #4. Since it uses a temporary file, it can be used for testing purposes before saving the linked file (using F2 from the File menu). When Interactive WarpLink shells to DOS and begins linking, the screen clears and displays a Now linking.... message. Interactive WarpLink will notify you of any errors or warnings that occur during the link by placing the output of all WarpLink messages in the Error Log window (#5). A successful link displays an information box upon return to Interactive WarpLink, instead of displaying the Error Log window (#5). The Project xe "Menu:Project"menu (ALT-P) contains two options: Load Select this option to load a previously saved Project file in order to replace all current settings with the settings contained in the Project File. Save Select this option to save all settings to a Project file. Interactive WarpLink will prompt you for the desired name. Interactive WarpLink comes with five project files on the WarpLink diskette: CLARION.PRJ is for use with xe "Clarion:Interactive WarpLink"Clarion 2.1. S87OVL.PRJ is for use with Clipper Summer '87. C501OVL.PRJ is for xe "Clipper 5:Interactive WarpLink"xe "Clipper:Interactive WarpLink"Clipper 5.01 and C52OVL.PRJ for CA-Clipper 5.2. DBU.PRJ is the fully linking Clipper program example for either Clipper Summer '87 or 5.01. C501OVL.PRJ and C52OVL.PRJ project files assume that you will use overlays with these languages and overlay xe "CLIPPER.LIB"CLIPPER.LIB modules. Each project file contains several typical option settings. Clipper users who experience difficulty or a significant slowdown when using these project files may wish to remove some of the overlaid CLIPPER.LIB modules. The link files created by these project files are also on the WarpLink diskette. They have the same name as the link file names specified in the corresponding project files. You can automatically load a project file on startup by typing the project name after IW, that is, IW [project_file_name]. The default file extension .PRJ is used if none is supplied. You may wish to use other options, in addition to those used in the project files, in order to speed up link or program execution times and free up memory. The Environment xe "Menu:Environment"menu (ALT-E) has two options, each with two sub-options: Defaults Select the Link File Extension sub-option to set the default extension used with the Save and Load options on the File menu. The default is .LNK. Select the Linker .EXE Name/Path sub-option to specify a new name and/or path for WARPLINK.EXE in case you renamed it previously or it is not along your PATH setting. Search Paths Select the Object Files sub-option to temporarily set the OBJ environment variable when Interactive WarpLink shells out to link. Select the Library Files sub-option to temporarily set the LIB environment variable when Interactive WarpLink shells out to link. Note that the OBJ and LIB environment variables in the master environment will be superseded by using the Search Paths options. If you do not set the search paths options, the master environment variable settings will be used. PRIVATE Chapter 11. tc \l 1 "Chapter 11. " xe "WarpHog"WarpHog Utility  WarpHog is a command-line, Terminate-and-Stay-Resident (TSR) utility that allows you to simulate a variety of memory situations. You can eliminate your guesswork when running under specific memory configurations, such as using a network server with only 400K free. Using WarpHog lets you test such conditions explicitly because it "hogs" free memory and leaves the specified amount of memory free. WarpHog Format Use the following format to load WarpHog into memory: WARPHOG [size] Size is the amount of free memory to simulate, in kilobytes (K) and may range from 200 to 640K. Using WarpHog Entering WarpHog at the command line without a parameter will display the copyright screen if the TSR is not resident in memory. If WarpHog is resident, entering WarpHog at the command line will remove the TSR from memory, freeing up the memory it "hogged" for other uses. Examples To simulate an environment with 400K free memory, enter: WARPHOG 400 To unload WarpHog, enter: WARPHOG xe "Informational Messages"Informational xe "WarpHog:Messages"xe "Messages:Informational"Messages WarpHog hogs all but ####K of memory. Execute WARPHOG with no parameters to unload. WarpHog has been loaded into memory successfully. The message displays the copyright notice and the amount of free memory (####). WarpHog and extra allocation have been removed from memory. WarpHog has been removed from memory and memory is restored to its original size. The message also displays the copyright notice. xe "WarpHog:Error Messages"Error xe "Error:Messages"Messages Invalid memory size !! Valid range is 200 to 640. The amount of free memory specified on the command line is outside the acceptable range. Specify memory within the 200K to 640K range. Could not make ###K available, only ###K DOS memory is free. The amount of free memory specified on the command line is larger than the amount of memory free within your environment (###). Try again by specifying a smaller amount of memory. WarpHog could not load, try a new memory size. This message indicates WarpHog did not load into memory. Try again by specifying a smaller amount of memory. PRIVATE Chapter 12. tc \l 1 "Chapter 12. " xe "WarpConv"WarpConv Utility  xe "Link Files:Converting"WarpConv is a command-line utility program that converts existing PLink-compatible link files into the link file format required by WarpLink. WarpLink uses a Microsoft Link and Borland TLink compatible script file format that is also known as positional. Linkers, such as PLink and RTLink, use or are based on a PLink compatible script format, also known as free format. Using WarpConv can shorten your learning curve if you are switching to WarpLink from one of these products. Technical Note The terms xe "Link file"link file, link xe "Script files"script file, linker script and xe "Response files"response file are used interchangeably. WarpConv Format Use the following format to start WarpConv at the DOS prompt: WARPCONV [options] [input_file] [output_file] Items in xe "Brackets"brackets are optional, WarpConv will prompt for file names if necessary. If no file extension is supplied, WarpConv will default to the extension .LNK. To specify a file name without an extension, place a period at the end of the name. Using WarpConv Like the other WarpLink utilities, WarpConv is easy to use. You specify an input file, an output file, and options as desired. You may either supply the input and output file on the command-line or WarpConv will prompt you for them. WarpConv will then convert your PLink response file to the Microsoft Link format. You can display a help screen by entering the following at the DOS prompt: WARPCONV ? xe "WarpConv:Options Summary"WarpConv xe "Options:WarpConv"Options Summary PRIVATE OptionDescription/ncDo not keep translator comments in WarpLink response file./noDo not automatically add OVLMGR.OBJ to object module list./nwDo not display any warnings following translation. WarpConv Options Details PRIVATE  /nc Do not keep translator comments in WarpLink response file. Description WarpConv automatically inserts translation comments at the beginning of the WarpLink xe "Response files"response file. The xe "WarpConv Options:/nc"/nc option will cause WarpConv to omit these comments in the WarpLink response file. PRIVATE  /no Do not automatically add OVLMGR.OBJ to object module list. Description WarpConv automatically adds the WarpLink overlay manager file to the list of object modules if overlay usage is detected. The xe "WarpConv Options:/no"/no option will cause WarpConv to omit the overlay manager file from the response file. PRIVATE  /nw Do not display any warnings following translation. Description WarpConv automatically provides warning feedback at the end of the translation process in certain situations where it detects possible incompatibilities. The xe "WarpConv options:/nw"/nw option will instruct WarpConv not to display these warnings. PRIVATE Chapter 13. tc \l 1 "Chapter 13. " Clipper xe "Symbol Table Compaction Utility:SP.EXE"Symbol Table Compaction Utility  Clipper Symbol Table Compaction Utility, xe "SP.EXE"SP.EXE, is a command-line utility program that compacts symbol tables for Clipper Summer '87 and Clipper 5 applications, thereby removing duplicate symbol table entries. Do not use SP.EXE if you use the /sp option of WarpLink because the /sp option directs WarpLink to compact the symbol table at linktime. This utility shrinks the size of your overlaid or nonoverlaid .EXE programs that were created using WarpLink and frees more xe "Memory:Conserving"memory for use by your program. SP.EXE Format Use the following format to start SP.EXE at the DOS prompt: SP INFILE [outfile] [/d] The default extension for the executable file is .EXE. The current directory and drive are used unless otherwise specified with the file names. If the outfile is not specified, SP.EXE will automatically create back-up copies of the INFILE executable (.EXE) and overlay (.OVL) files. The back-up files will use .EXK and OVK extensions, respectively. Use the /d option to retain the original time/date stamp on the executable file. xe "SP.EXE:Informational messages"xe "Informational Messages"Informational xe "Messages:Informational"Messages NOTE: No duplicate symbols! No file(s) created. If SP determines that no further compaction can be performed, processing is halted. Since even a simple application generally has at least some duplicate symbols, this message will probably only occur if you attempt to run SP.EXE on a file that has been compacted already. Renaming files ... Renaming files to .EXK and OVK requires calls to DOS that may result in a short delay if your system has a large number of files and directories. Processing Internal Overlay #... This message indicates that SP.EXE is still active and it detects an internal overlay file structure. Processing External Overlay #... This message indicates that SP.EXE is still active and it detects an external overlay file structure. Successful symbol-compaction This message indicates SP.EXE has finished. xe "SP.EXE:Error messages"Error xe "Error:Messages"Messages ERROR: Illegal character(s) in Filespec. At least one illegal character was found in the source or destination file, Acceptable characters include: A-Z, 0-9, _ @ - { } ! " # $ % &. ERROR: Inadequate memory to run SP.EXE. A memory-allocation request to DOS failed. SP.EXE requires two buffers for symbols. Each buffer must be the size of the original symbol table plus an additional 64K buffer for loading source program code and several small buffers for file headers. ERROR: Invalid Target or unknown Overlay Mgr. Required signature bytes in the source file could not be located. This may result from a file that was not linked by using WarpLink or not compiled by using Clipper. ERROR: Bad overlay name or path too long. The embedded overlay name in the WarpLink OVLMGR data cannot contain a path, and is thus limited to a total of 12 characters, including file name and extension. WarpLink and WarpMod observe this limitation. The OVLMGR data may have been damaged or patched. ERROR: Syntax error on command line. The only command line arguments supported by SP.EXE are the source file name, the output file name (optional) and d, /d or -d for the time/date stamp option. ERROR: Unable to open overlay file. SP.EXE could not locate or open the overlay file name within the WarpLink OVLMGR data segment. Although the embedded overlay name does not contain path information, SP.EXE will use the path provided for the source file. You should make sure that the appropriate overlay file is available in the same directory as the source file. ERROR: Unable to correctly rename file(s). In order to anticipate input and output files with identical names and avoid making backup copies, the compacted file is generated with the file extensions of .EQE (for the root) and .OVE (for the overlay if present). Upon successful completion, the names of the files are adjusted to rename the compacted files (.EXE and .OVE) and the original files (.EXK and .OVK) by using a temporary name of SVD{D$$$}.$$$. If a DOS error occurs during the renaming process, files may be left in an indeterminate state. The temporary file will be transiently located in the current directory. ERROR: Unknown WarpLink Overlay Manager. SP.EXE supports all valid releases of WarpLink. ERROR: Invalid symbol encountered. Symbol data-structures are checked for consistency with known Clipper requirements while SP.EXE is running. This error message may result from a damaged symbol table in the source file. ERROR: Invalid compaction calculation. Pointers to the start and end of the source symbol table are mutually inconsistent. This message may result from a damaged or unknown source file. ERROR: Invalid file length calculation. The calculated length for the load-image of the newly compacted file is too large. ERROR: Procedure code parsing error. SP.EXE has to parse through tokenized Clipper code in order to adjust symbol references. A parsing error has occurred. The message may result from a damaged source file with corruption of the tokenized code. DOS xe "Error:DOS"Errors ERROR: Unable to open target file. ERROR: Unable to set file pointer. ERROR: Unable to read target file. ERROR: Unable to close target file. SP.EXE could not open one of the required files. Each of the messages listed above probably results from an error in specifying the file name, inadequate handles, or denial of access to the file due to network status or file attribute. ERROR: Target may have been corrupted. A fatal error occurred while the output file was being written. The file may be damaged and lost clusters may result. Delete the output file and run the DOS command, CHKDSK (/f), to check (and remove) lost clusters. xe "SP.EXE:Examples"Examples To display the copyright screen, entering the following (without parameters): SP Assume SAMPLE1 refers to an overlaid application with an executable file, SAMPLE1.EXE and you want to overlay SAMPLE1.OVL. Enter the following: SP SAMPLE1 In the example above, SP.EXE will copy these files to SAMPLE1.EXK and SAMPLE1.OVK, remove duplicate symbols from the original files and create new SAMPLE1.EXE and SAMPLE1.OVL files. Assume SAMPLE2 refers to a nonoverlaid application with the executable file SAMPLE2.EXE. Use the following to remove duplicate symbols from SAMPLE2.EXE and create a new executable file, SAMPLE3.EXE: SP SAMPLE2 SAMPLE3 PRIVATE Chapter 14. tc \l 1 "Chapter 14. " xe "SmartMem Functions for Clipper Summer '87"SmartMem Functions for Clipper Summer '87  WarpLink has been released to public domain. We do not have permission to release the licensed Smartmem subset to public domain, and those files are not included in this release. PRIVATE Chapter 15. tc \l 1 "Chapter 15. " Norton Guides Help System  The xe "Norton Guides help system "Norton Guides help system provides a great deal of useful information about WarpLink. You can use it to answer many common questions and find solutions to many common problems. The system is easy to use and contains extensive on-line documentation. A limited description is included here for your reference. Loading On-Line Help Norton Guides is a Terminate-and-Stay-Resident (TSR) program. WarpLink contains the database file entitled {WARP}.EXE that provides on-line help if you have loaded the Norton Guides TSR. Although WarpLink does not contain the Norton Guides (NG.EXE), it is available alone or with many other products. Use the following format to start Norton Guides at the DOS prompt: NG Invoking On-line Help To invoke the help system after loading it, press the Shift and F1 keys. NG.EXE will take up approximately 70K of memory. To display the options menu, press O (or highlight the Options entry) and press the Enter key. Then press D (or highlight the Database entry) and press the Enter key to display the database options. To display WarpLink help, highlight the WarpLink database and press the Enter key. Unloading On-Line Help You may wish to unload NG.EXE in order to recover memory when running a large application. To unload the Norton Guide TSR, invoke the help system and select the Options menu. Then select Unload. Press the Enter key at the prompt for unloading the NG system. Expert xe "Help:Expert"Help WarpLink has been released to public domain. We do not have permission to release the licensed Expert Help files to public domain, and those files are not included in this release. PRIVATE Chapter 16. tc \l 1 "Chapter 16. " xe "Direct Library Module Specification"Direct Library Module Specification  Libraries frequently contain modules that can be overlaid and modules that cannot be overlaid. To be safe, many developers will put the entire library into the root. WarpLink does not require this practice because you can pull individual modules out of the library by using xe "Library:Direct library module specification"direct library module specification. Direct library module specification also is called xe "Library:Module extraction"module xe "Extraction"extraction. Direct Library Module Specification Format Module specification is very simple to use. Just list the name of the library and a colon, followed by the module name to extract a particular module from a library. In the following example, MODULE1 of LIB1.LIB will be overlaid, while the rest of the library will be in the root: /OP:M /R (OBJ1+OBJ2)+OVLMGR,,, (LIB1:MODULE1)+LIB1 Using Direct Library Module Specification There are two important notes concerning module extraction. First, you must list the modules to be extracted before the corresponding library or object file name. WarpLink will use the first instance if a module is declared twice within an object file list or library file list. Listing the library or object file before the module specification would negate its use. Do this: /OP:M /R (OBJ1+OBJ2)+OVLMGR,,, (LIB1:MODULE1)+LIB1 Not this: /OP:M /R (OBJ1+OBJ2)+OVLMGR,,, LIB1+(LIB1:MODULE1) Second, the modules to be specified do not have to be in the root. The list of modules can overlaid and the corresponding object or library file can be in the root. Or, the list of modules to extracted can be in the root and the corresponding object or library file can be overlaid. The following example shows overlaying only the library module, MODULE1: /OP:M /R (OBJ1+OBJ2)+OVLMGR,,, (LIB1:MODULE1)+LIB1 The following example shows overlaying all of the library except MODULE1: /OP:M /R (OBJ1+OBJ2)+OVLMGR,,, LIB1:MODULE1+(LIB1) Using module extraction will slow down the xe "Linking:Speed"link process because the linker must search the entire .LIB file for each module name. To speed up the link process, you should consider either using the /ql option or breaking the overlayable and non-overlayable portions of the library into separate libraries that can be overlaid and placed in the root without using module extraction. When using library module specification with the xe "Link options:/ql"/ql or xe "Link options:/clpi"/clpi options, be sure to list the options before the library list. Placing these options after the library list may cause WarpLink internal errors. PRIVATE Chapter 17. tc \l 1 "Chapter 17. " Using D-format Dynamic Libraries  WarpLink's xe "D-format Dynamic Libraries (DDLs)"D-format Dynamic Libraries (DDLs) are a powerful tool for developing several programs which share many of the same routines or to provide replaceable modules for the same program. A .DDL file is a collection of modules, in much the same way as a .LIB file is a collection of modules. There is a significant difference, however. The modules contained in a .DDL file are used by a program when it begins operation, instead of being built into the program during linking. Just like a .LIB file, however, only those modules that are needed to run the program are used. Unlike some other DOS dynamic link library schemes, just listing a module in a .DDL file does not mean that it must be linked into the program. xe "DDLs:XMS use"xe "DDLs:EMS use"DDLs are not for everyone. They require a machine that has at least 640K of free LIM EMS 4.0 or XMS to hold the program while it is being built. Because DDLs perform a full link at program startup time, depending upon the size and structure of the program there may be a noticeable -- potentially significant -- delay before the program begins to execute. For this reason, it is strongly recommended that you either use DDLs only on machines with 386 and higher level processors, or design your programs to accommodate the startup delay. DDLs will not affect your program execution speed after startup, once the program has been built operation proceeds at the same pace as a program that does not use DDLs. DDL xe "DDLs:Terminology"Terminology xe "DDLs:Master"Master .DDL files are those .DDL files that control the program using dynamic link libraries. Runtime options specified when creating the master .DDL file are those which are in effect when the program is built and executed. Runtime options listed for other .DDL files used in building the program will not be used. When the master .DDL file is created, another file is also created with the same base name as the .DDL file but with the .EXE extension. This small .EXE file contains loader code that kickstarts the operation of the dynamic link library process. xe "DDLs:Support"Support .DDL files are those .DDL files that supply modules to the master .DDL file. Runtime options specified when creating a support .DDL file are not in effect when the program is built (but may be used if the support .DDL file is also a master .DDL file for a different program). A master .DDL file may use up to fifteen support .DDL files. Master and support .DDL files differ only in how they are used. Depending upon the situation, a master .DDL file may be a support .DDL file and vice versa. In fact, a .DDL file may be a support .DDL file to a particular master .DDL file for one program, then become a master .DDL file with the old master file being a support file in another program. The .EXE file being run determines which .DDL file is the master file. Modules in both master and support .DDL files may be overlaid or not (in the root). There are two types of modules besides overlaid and root. They are required and elective modules. xe "DDLs:Required modules"Required modules are those modules that will always be linked into the program when the .DDL file is used. Required modules will be present in the final program whether or not they resolve symbol references. You specify required modules by listing them in the object file list. In the following example, DBU.OBJ, ROUT.OBJ, and THINGS.OBJ are all required modules from MISC.DDL file, with DBU being an overlaid module: WARPLINK /DDL (DBU) ROUT THINGS,MISC,,CLIPPER (EXTEND) DBFNTX Placing a library file in the object file list is not recommended. Doing so will force all modules within the library file to be linked into the program. Typically, you only want library modules to be brought into a program if they are needed. xe "DDLs:Elective modules"Elective modules are those modules that will be linked into the program only if they resolve a symbol reference while the program is being built. You specify elective modules by listing them in the library file list. In the previous example, all modules in CLIPPER.LIB, EXTEND.LIB, and DBFNTX.LIB of MISC.DDL are elective modules and may or may not be linked into the program. All modules used in EXTEND.LIB will be overlaid. DDL xe "DDLs:Options Summary"Options Summary Three WarpLink command options are used for creating and using DDLs. PRIVATE OptionDescription/ddlCreate D-format dynamic library./dm:nameUse DDL manager file name./udl:nameUse named D-format dynamic library at runtime. DDL Options Details PRIVATE  /ddl Create D-format dynamic library. Description The xe "DDL options:/ddl"/ddl option instructs WarpLink to create a .DDL file containing the object modules and libraries listed. It may be either a support or a master .DDL file, depending upon how it is later used. If no required modules are specified, then the .DDL must be a support file and no .EXE file is created. If one or more required modules are specified, than an .EXE file is created as well. PRIVATE  /dm:name Use DDL manager file name. Description The xe "DDL options:/dm"/dm option tells WarpLink to place code from a particular DDL manager file in the .DDL file. If the .DDL file is a master .DDL file, this DDL manager code will be executed to build the program. Even if the .DDL file is a support file, it will contain code from the DDL manager. The /dm option is not necessary if you wish to use the default DDLMGR.DAT file. When using the /ddl option WarpLink will use the OBJ environment variable to search for the DDL manager file if it is not in the current directory. You may also explicitly list a directory other than the current directory or one in the OBJ environment variable by using the /dm option. For example, the option /dm:F:\DDL\DDLMGR.DAT will cause WarpLink to always search for the DDLMGR.DAT file in the F:\DDL directory. PRIVATE  /udl:name Use named D-format dynamic library at runtime. Description The xe "DDL options:/udl"/udl option allows you to specify a list of support .DDL files for a master .DDL file. The master .DDL file will search each support .DDL file listed in turn to resolve symbol references. Up to fifteen separate support .DDL file names may be supplied to a master .DDL file. The /udl option only supports one file name each time it is used. .DDL files specified by the /udl option need not be present -- or even exist -- when the option is used. The support files need only be present at runtime. Using xe "DDLs:Command options"Command Options Both elective and required modules contained in a .DDL file may be overlaid. xe "DDLs:Overlays"Overlays are specified in the same way as they are during the normal link process, that is, the object modules or libraries are placed in xe "Parentheses"parentheses. This flags to the DDL manager that the modules, if used, will be overlaid. When creating a .DDL file with the /ddl option, no .OBJ files need to be listed in the object module list. This is different from the normal linking operation of WarpLink that requires at least one .OBJ file to be listed. Not using .OBJ files allows you to create a .DDL file from only library files. Creating a .DDL file from only library files is a common occurrence. If no .OBJ file is specified, then a .DDL file name must be listed because there is no default .DDL file name to generate from the first .OBJ file name. The .DDL file name is specified in the same manner as a .EXE file name is specified in a normal link: either after the first comma following the WarpLink options list or on the first separate line following the options list. If there are any required modules contained within the .DDL, then a loader .EXE file is also created when creating a .DDL file. Be cautious when using the /ddl option to avoid inadvertently overwriting a pre-existing .EXE file. For example, if you create a CLARION.DDL file using the following command line: WARPLINK /DDL CLARION CLARION0,,,CLARION1 CLARION2 WarpLink will create two files: CLARION.DDL and CLARION.EXE, by using the code in CLARION.OBJ, CLARION0.OBJ, CLARION1.LIB, and CLARION2 modules. Any pre-existing CLARION.EXE file will be overwritten by this process. To avoid overwriting a pre-existing CLARION.EXE file explicitly, specify a different DDL name (e.g. create a CLAR.DDL and CLAR.EXE file) as follows: WARPLINK /DDL CLARION,CLAR,,CLARION1 CLARION2 Alternatively, you can specify a different directory for the resulting files. If there are no required modules within a .DDL file (all are elective) then no loader .EXE file is created. DDL xe "DDLs:Runtime Operation"Runtime Operation Upon startup, the .EXE loader will load the master .DDL file's DDL manager code into memory and transfer control to that code. The DDL manager will allocate 640K of EMS or XMS, then begin building the program to execute. First, all required modules in the master .DDL file are loaded. Then, all the elective modules from the master .DDL file that resolve symbol references are brought in. The process is repeated for each support .DDL. If unresolved symbols remain, another pass is performed on the elective modules of each .DDL, repeating until either symbol references are resolved or no elective module is added in a pass. Once all symbol references are resolved, control passes either to the overlay manager portion of the DDL manager file or directly to the program code if there are no overlays. The EMS or XMS allocated by the DDL manager is freed prior to program execution or upon error termination. Any allocated EMS or XMS will be available for the program's use, or for the overlay manager portion of the DDL manager depending upon the EMS and XMS options specified when creating the master .DDL file. As overlays are needed, they are loaded from the DDL files and fixed-up to the proper addresses by the DDL manager. Treat DDL files as overlay files, do not remove the program's access to them while it is executing. The DDL managers report any unresolved externals that may remain after building the program and then terminate the process with a nonzero return code to indicate an error. This will help you track down any errors in building or specifying the .DDL libraries. You cannot deliberately leave a symbol unresolved when using .DDL libraries as the DDL manager will report the unresolved external as an error. If you wish to provide subset capability to your program when using DDLs, then you should stub out any symbols or routines with a dummy reference or return, so that they do not cause an unresolved external error. WarpLink supports a xe "DDLs:DDLPATH environment variable"xe "Environment variable:DDLPATH"DDLPATH environment variable. This environment variable allows you to specify the location of .DDL files at runtime. When a program using dynamic libraries begins execution, the DDL manager will look for the .DDL files in the current directory. If the DDL manager does not find the necessary .DDL files, it will search the path or paths specified by the DDLPATH environment. Notes Do not link in the xe "Overlay manager :With DDLs"overlay manager files, OVLMGR.OBJ, CNOVLMGR.OBJ, or C5OVLMGR.OBJ when using .DDL files. The DDL manager file contains its own overlay manager routines. Linking in an unnecessary overlay manager file will simply increase your memory and file size overhead. Do not use the /op option with the minus sign (-) setting with DDLs. You must either use an explicit overlay pool size (/op:size) or the minimum overlay pool setting (/op:m). Version Note Unlike previous versions of WarpLink, the DDL managers will perform as many search passes as necessary on the master and support DDL files to resolve all symbol references in the program as it is built. This makes the order of DDL specification much less critical, allowing a .DDL module to reference a symbol resolved by a module in a previously searched .DDL file. Benefits Of Using xe "DDLs:Benefits of using"DDLs One of biggest benefits of DDLs is that common routines and modules can be shared among multiple programs while existing in only one file. This can lead to significantly smaller disk space requirements when several programs are used that share the same .DDL files. Another major benefit of DDLs is that they are completely independent of each other. This allows for easy replacement or upgrade of various modules and drivers for a program or set of programs without the need to replace all the associated DDLs. Support .DDL files are selected by the master .DDL file based solely upon the .DDL name at program startup. You can easily supply different versions of the same .DDL file for different users and environments. You can perform an upgrade of a particular set of modules without doing anything more than rebuilding the specific .DDL file that contains those modules and distributing that one modified .DDL file. Finally, D-format dynamic libraries allow you to overlay the same code that can be overlaid during the normal link process. For example with Clipper programs, C and assembly language modules may be overlaid in addition to standard Clipper code. This capability can provide a significant advantage over the standard pre-linked libraries. Further, only those modules required by the program will be used by the DDL manager to build the program. Technical Notes DDL managers do not support the xe "DDLs:Overlays"overlaying of xe "Small model code"small model code. You cannot use programs with DDLs if they use near calls between overlays or between an overlay and the root. DDL managers do not support custom overlay manager error handlers. Do not use internal overlay manager routines with DDLs. When using DDLs with overlays, memory usage may be somewhat higher than with regular programs. Several additional internal tables are maintained by the DDL manager. If your program does not use overlays, it should operate identically in all respects to a program linked without DDLs. When running an overlaid program with multiple .DDL files, more file handles will be used than the one file handle used by an overlaid program not using DDLs. The number of file handles used by .DDL files when overlays are used is equal to the number of total .DDL files used by the program, that is, one for the master .DDL file plus one for each support .DDL file. No file handles are used by DDLs in a nonoverlaid program after the program begins execution. However, while the program is being built by the DDL manager, the number of file handles used transiently equals the total number of .DDL files used (as with overlaid programs.) Support .DDL files specified by the /udl option cannot be nested. If a support .DDL file used by the master .DDL file to build a program has support .DDL files in turn, those support .DDL files will not be linked into the program. All support .DDL files for the master .DDL file must be listed when creating the master .DDL file. Clipper User Note xe "Clipper:and DDLs"Clipper users should note that the dynamic library managers currently do not perform automatic Clipper xe "DDLs:Clipper symbol table compaction"symbol table compaction. You may wish to create .CLP files when creating object modules to reduce the number of duplicate symbols in your program when using DDLs. Since WarpLink cannot know which modules are going into a program that uses DDLs until execution, it cannot pre-pack the Clipper symbol table. Clipper 5 User Note Clipper 5 users must use the /dm:C5DDLMGR.DAT option in order to use overlays within DDLs. Use the default DDL manager file (DDLMGR.DAT) with Clipper 5 if overlays are not used. Clarion User Note xe "Clarion:and DDLs"Clarion users must use the /dm:CNDDLMGR.DAT option in order to use overlays within DDLs. Use the default DDL manager file (DDLMGR.DAT) with Clarion if overlays are not used. PRIVATE Chapter 18. tc \l 1 "Chapter 18. " Other WarpLink Features  WarpLink supports several additional features that are useful for advanced-level programmers. They are: the xe "$$_COM_END variable"$$_COM_END internal linker variable, the xe "$$_EXE_IMAGE_SIZE :variable"$$_EXE_IMAGE_SIZE internal variable, support for custom overlay manager error handler and overlay file manipulation, and support for small model code overlaying plus overlay-to-root vectoring. The $$_COM_END Variable An age-old problem in the way DOS deals with .COM files is the decision to leave memory management up to the .COM file. When an .EXE file loads, DOS allocates to it only the memory it requests automatically. When a .COM file loads, all available memory is allocated to it. In most situations, the DOS memory allocation procedure for a .EXE file is preferred over that for a .COM file because other programs, such as TSRs, can make use of the memory the .COM file does not need. $$_COM_END is a predefined public symbol that your program can use for just that purpose. $$_COM_END is a symbol which represents the linker-computed quantity of memory that is required by the code and data segments of your program. Declare it as an EXTRN in your program and use it with INT 21h function 4Ah to deallocate all except the amount computed, plus whatever stack you need. $$_COM_END does consume 2 bytes for storage. Therefore a .COM file is two bytes larger than normal if you declare $$_COM_END as an external. If $$_COM_END is declared as public, the linker assumes that you wish to use the variable name for your own purposes and does not treat $$_COM_END as a special variable. $$_COM_END automatically adjusts for the Program Segment Prefix (PSP) size of 256 bytes when computing the required memory. $$_COM_END depends upon the first object module that contains a class 'CODE' segment (typically _TEXT) to have the segment listed as the very first SEGDEF (segment definition) record. Most languages that support .COM files do this automatically. Example The following an assembly language code fragment shows sample use of the $$_COM_END variable to reduce the .COM file memory requirements: EXTRN $$_COM_END:WORD ... MOV AX, $$_COM_END ; Get program size. ADD AX, STACKSIZE ; Add stack. TEST AL,1 ; Check if odd byte-aligned stack JE @@EVEN ; No: even byte alignment. INC AX ; Yes it's odd. Bump one. @@EVEN: MOV SP, AX ; Initial stack = program size + stack size SHR AX, 1 ; vide AX by 16. SHR AX, 1 SHR AX, 1 SHR AX, 1 INC AX ; Round up a paragraph. MOV BX, AX ; BX = new size of memory block in paragraphs MOV AH, 4AH ; Resize Memory Block, ES=PSP INT 21H ; Returns w/ CF=1 on error. JNC @@NOERROR ; If CF=0, all is well. MOV AH, 4CH ; Error, exit to DOS INT 21H ; via function 4Ch. @@NOERROR: ... ; Success. The $$_EXE_IMAGE_SIZE Variable If public symbol xe "$$_EXE_IMAGE_SIZE:variable"$$_EXE_IMAGE_SIZE is declared and the program is linked without the /c option (therefore producing an .EXE file), WarpLink will place the doubleword load image size of the file in the $$_EXE_IMAGE_SIZE symbol. WarpLink will not create the symbol if it is not declared. This feature is roughly analogous to the $$_COM_END variable created when the /c option is used. However, it takes into account the more complex nature of .EXE files. You must allocate at least four bytes for the variable $$_EXE_IMAGE_SIZE. Otherwise, WarpLink will write beyond the bounds of the variable, possibly causing program malfunction. Variable space is not automatically added to the program by the linker as is done with the $$_COM_END variable. Using the $$_EXE_IMAGE_SIZE variable provides the capability to easily determine the end of a program in memory in order to free up excess memory for DOS or for other programming purposes. Example The following assembly language code fragment shows sample use of the $$_EXE_IMAGE_SIZE variable to shrink the memory allocated to the program to its minimum load size: PUBLIC $$_EXE_IMAGE_SIZE ... $$_EXE_IMAGE_SIZE DD ? ... MOV BX,WORD PTR $$_EXE_IMAGE_SIZE ; load image size low word MOV DX,WORD PTR $$_EXE_IMAGE_SIZE+2 ; load image size high word ADD BX,15 ; round up to next paragraph ADC DX,0 ; carry to high word SHR DX,1 ; convert to paragraph count RCR BX,1 ; /2 SHR DX,1 RCR BX,1 ; /4 SHR DX,1 RCR BX,1 ; /8 SHR DX,1 RCR BX,1 ; /16, bx holds paragraphs of load image size ADD BX,10H ; adjust for Program Segment Prefix size MOV AH,4aH ; resize memory block, es -> PSP INT 21H Custom Overlay Manager Error xe "Error:Handlers"Handlers The WarpLink xe "Overlay manager:Error handlers"overlay manager has several internal routines and variables accessible by the linked program. These internals allow the program to change the overlay manager's behavior when it encounters an error and to restore control back to the program. They also allow you to rename and move the overlay file to a different directory or drive while the program is running without error. Included in the WarpLink package are three files demonstrating use of the WarpLink overlay manager internals. ERRHAND1.C and ERRHAND2.C are extensively commented C source files demonstrating a simple error handler that restores control to the program when an error occurs in the overlay manager and allows the program to either attempt to recover from the error or to provide a more protected exit to DOS. Also, these files should give you an idea of how you can move an overlay file to a different drive or directory during the program's operation. ERRHAND.ASM is the source file for a sample error handler written in assembly language that you can link into a program. The ERRHAND error handler displays one line of feedback describing any overlay manager error that occurred before termination to DOS. Small Model Code Overlays and Overlay to Root Call xe "Vectoring"Vectoring When set up properly, WarpLink can overlay many xe "Overlays:Small model code"xe "Overlay:Small model code "xe "Small model code"small model code structures, including direct near calls from an overlay to the root, from an overlay to another overlay, and from the xe "Overlays:Root calls"root to an overlay. In each case, direct near calls are vectored (redirected to and from) through the overlay manager first, allowing the overlay manager to load overlays as necessary for proper overlay management. Vectoring of xe "Overlaying:Direct near calls"direct near calls is specified by using square xe "Brackets"brackets ([ ]), instead of parentheses to indicate which files are overlaid. WarpLink recognizes bracketed overlays as overlays which need additional internal processing to allow direct near calls between overlays. xe "Overlaying:Indirect near calls"Indirect near calls cannot be vectored through the overlay manager. Do not overlay code which contains indirect near calls to another overlay or to the root. Use of indirect near calls between overlays or between an overlay and the root may cause your program to operate erratically or fail during execution. However, you may safely overlay code which contains indirect near calls that remain within the original overlay. You can use brackets when specifying overlays in order to vector calls through the overlay manager. Normally, calls from an overlay to the root are called without vectoring. The call goes directly to the root from an overlay without the intervention of the overlay manager. Because those overlay-to-root calls do not have overlay manager overhead, your program runs more efficiently. However, when you use brackets instead of parenthexe "Parentheses"ses to specify overlays, calls from an overlay to the root are vectored through the overlay manager. This ensures that the overlay is always loaded in the same location of the overlay pool after the program returns from the root function or procedure. Without root to overlay vectoring (or xe "Link options:/r"/r reloading), the overlay may be loaded in a different location in the overlay pool. The location may differ if the root function or procedure called by the overlay calls other overlays which swap out the original overlay before returning to the root and then the original overlay. Although the overlay manager modifies the return and execution address to this new overlay address, some code structures are intolerant of a segment address change. Storing the load address in a variable before swapout and attempting to re-use it after return may cause problems, for example. xe "Runtime speed"Overlay-to-root vectoring can cause a slight speed degradation in an operating program and therefore is not recommended if it is not necessary. Typically, if you use the /r option, you do not need to use xe "Brackets"brackets because the original calling overlay will be loaded at the same address when the root code returns. Even without the /r option, programs which do not store the absolute address of an overlaid procedure will operate correctly without using brackets. The return to the overlay is handled properly even if the segment load address of the overlay changes. You must always use brackets when overlaying small model code that has direct near calls to another overlay or the root, regardless of whether you use the /r option. PRIVATE Chapter 19. tc \l 1 "Chapter 19. " Using xe "Overlay pool:Sizes below minimum required"Overlay Pool Sizes Below Minimum Required  With planning and work by the programmer, some programs will operate correctly with overlay pool sizes smaller than the linker-set minimum. You may be able to set the /op option to provide significant memory savings. Although the following discussion is written for Clarion users, many of the details concerning use of an overlay pool smaller than the linker-set minimum also apply to other languages. If you are not using xe "Clarion:/op\:m option"Clarion or another language which requires use of the /r option, the linker-set overlay pool minimum size (xe "Link options:/op\:m"/op:m) will always be the size of the largest overlay rounded up to the next 1K boundary. The overlay pool cannot be smaller than the largest overlay. Should you attempt to set the overlay pool below the size of the largest overlay with an explicit /op setting, WarpLink will display the 'Minimum overlay allocation exceeds maximum pool size, size adjusted' message and set the overlay pool to the size of the largest overlay automatically. You can use WarpMod to override the fail-safe size mechanism, but it will invariably cause your program to fail when encountering a larger overlay. If you are using Clarion and you experience problems reaching your overlay pool size goal, first make sure that you are not overlaying IDLE procedures. Clarion reports IDLE procedures so you can easily detect and avoid placing them in an overlay. Overlaying IDLE procedures will cause Clarion internal errors. Technical Issues The linker option /op:m is called Overlay Pool Minimum option for good reason. The /op:m setting is the minimum overlay pool size guaranteed by the linker to work with the /r option. If you set the overlay pool below that size, then you need to be aware of the consequences. The amount below the linker-set minimum overlay pool size you can use without encountering internal errors will vary. There are several reasons for this. Different overlay manager versions may load overlays differently and internal overlay load algorithms may change with each version of overlay managers. Separate passes through the program load and call overlays in a different order, and thus affect minimum pool size. Varied operating machine memory configurations may load overlays at different addresses in the overlay pool. Minor coding changes can put an overlay into the next 1K boundary and completely change the overlay loading pattern. If you depend upon an overlay pool size less than /op:m based strictly on empirical testing, then several factors unrelated to the overlay manager can terminate your program with an internal Clarion error. With an understanding of the issues involved, however, you can drop below the /op:m setting, sometimes significantly, and still achieve stable program operation without exhaustive testing of all possible overlay call and load combinations. Many people do this with xe "Clarion:Overlaying"Clarion and other languages. However, the program developer, rather than WarpLink's algorithms, must take on the responsibility for overlay management. The WarpLink guarantee of stable overlay management with no Clarion internal errors stops at the /op:m setting. With this in mind, the following paragraphs are a discussion of how to safely drop below the /op:m setting. xe "Clarion:Passing pointers"Clarion requires that the immediate parent procedure calling a child procedure remain in memory after the child procedure has been loaded. This sets an absolute lower limit on the overlay pool size because both parent and child procedure must fit into the pool simultaneously. If there are gaps in the overlay pool, as there typically are after the program has been running with overlays of varying sizes being loaded in and swapped out, the overlay pool must be larger than the simple sum of the overlaid parent procedure size plus the overlaid child procedure size. The worst case scenario requires an overlay pool size equal to (parent size in K) + 2 * (child size in K) - 1K. If you know the size of the largest direct parent-child overlaid procedure calling chain, you can compute a more accurate minimum overlay pool size than WarpLink. Without knowledge of the program's calling structure, WarpLink assumes a worst case load scenario by using the absolute largest and second largest procedures. The program developer, however, can base the minimum overlay pool size on the largest parent-child combination that will occur when the program operates. Complicating matters, with Clarion all procedures in a pointer-based parameter chain must be present. If you pass pointer-based parameters deeper than the immediate child procedure, then the grandfather (parent of the parent procedure) must be present and loaded in the overlay pool due to its participation in the parameter chain. This ancestry extends for as long as the parameter is passed down the line of procedures. This restriction on parameters can greatly increase the overlay pool worst case minimum size. Therefore, passing parameters across multiple layers of overlaid procedures is not recommended and, in fact, can even exceed the requirements of the WarpLink /op:m setting. You should keep passed pointer-based parameters strictly between the immediate parent overlaid procedure and the child overlaid procedure in order to avoid overlay management problems. The use of xe "Clarion:Buffer procedures"buffer procedures can help immensely if you are not passing parameters in a Clarion program. Buffer procedures are small routines that are called solely to have the buffer procedure call another routine. Since only the immediate parent and child overlay need to reside in the overlay pool at the same time, placing a buffer procedure between a large procedure calling another large procedure reduces the overlay pool size requirements for that calling chain. For example, assume a parent overlaid procedure of size 20K calls a child of size 16K. The overlay pool needs to be (20K)+2*(16K)1 = 51K to handle the worst case scenario of this overlaid procedure calling chain. A buffer procedure that is placed between the two can safely swap out the parent. The parent calls the buffer and the buffer calls the child. Assuming the buffer procedure is 1K, the worst case for the same overlaid procedure calling chain is (1K)+(2*16K)1K = 32K. That is a significant difference of 19K. However, using buffer procedures when passing pointer-based parameters makes matters worse. Not only do the parent and child still have to be in the overlay pool, but so does the buffer procedure. Depending upon where the buffer procedure loads in the pool, it can affect the pool requirement completely out of proportion to its size. For example, the buffer may reduce the free area in the overlay pool enough so that the child overlay that normally fits there cannot load in that area. Naturally, when using buffer procedures you have to buffer between all of the overlaid procedure calling chains in order to reduce size requirements and actually drop the overlay pool size. For example, if you cut the overlaid procedure calling chain in one place by 20K, but not in another calling chain with the same xe "Memory:Conserving"memory requirements, you cannot drop the overlay pool size. For any language, if you wish to reduce the minimum overlay pool size, you should consider making your code modular, thereby creating smaller and more numerous procedures, functions, and routines. This avoids the buffer-parent-child issue by breaking up huge overlaid procedures that reduce the efficiency of the overlay manager's ability to place code in the overlay pool. WarpLink assumes a worst case overlaid procedure calling chain. /op:m calculates the size of the overlay pool by using the following equation: [second largest overlay + (2 * largest overlay) - 1]. For example, to achieve a minimum overlay pool size of 74K, you must have at least two procedures that are at least 25K, or one procedure that is 26K and one procedure that is 23K. If you have a largest procedure of 26K and a second largest procedure of 23K and you trim the 26K procedure down to 23K, your minimum overlay pool drops from 74K to 68K -- effectively doubling your free memory gain for every kilobyte of size reduction in the largest overlaid procedure. The recommended maximum overlay size (procedure size plus static and local data with Clarion or code segment with other languages) is 22K. This will allow you to safely use the /ox option if desiredd and will also help to keep your overlay pool size to manageable levels. PRIVATE Chapter 20. tc \l 1 "Chapter 20. " xe "Common questions and answers "Common xe "Questions and answers"Questions and Answers About WarpLink  The following commonly asked questions and their answers may help you use WarpLink. These questions were compiled based upon experience with the WarpLink user base and the application development community. Using Overlays What is an overlay pool? An xe "Overlay pool:Defined"overlay pool is the separate area of memory that WarpLink reserves while your program runs. All of your overlaid functions and procedures are swapped into and out of this overlay pool only; no other memory is used. How do you create xe "Overlay:Creating"overlays with WarpLink? In a xe "Response files:Creating overlays"response file or from the DOS command line, .OBJ files and .LIB files that are surrounded by parentheses or xe "Brackets"brackets are put into an overlay; those that are not surrounded by parentheses or brackets are put into the root. Remember that if you are using overlays you need to include the proper overlay manager file (OVLMGR.OBJ, C5OVLMGR.OBJ, or CNOVLMGR.OBJ) in your object file list. Can library files (.LIB files) be overlaid? Absolutely. xe "Libraries:Overlaying"They are overlaid the same way that object files are overlaid: put parentheses or brackets around them. Note that Clarion library files do not contain xe "Clarion:Overlaying"Clarion code and cannot be simultaneously overlaid with Clarion modules. Also, be aware that for many reasons, language runtime libraries cannot be fully overlaid. See the question about types of code that cannot be overlaid in the Overlay Technical Information section for a more detailed discussion. Is there any difference between having all of my object files within one set of parentheses and each individual object file in its own set of xe "Parentheses"parentheses? There is no difference whatsoever. In either case, WarpLink will create a single .EXE file and a single .OVL file if you are not using internal overlays. Does WarpLink create multiple .OVL files? No. If you are using xe "Overlays:Multiple overlay files"overlays only one .OVL file will be created. If you are using internal overlays, the overlay file will be appended to the .EXE file and no .OVL file will be present. Overlay Technical Information Does WarpLink support xe "Overlays:Static"static overlays? No. WarpLink efficiently and effectively uses dynamic overlays without any program changes. WarpLink supports only dynamic overlays. Does WarpLink use interrupts for overlays like some other linkers? WarpLink does not use an xe "Overlays:Overlay manager interrupt"overlay manager interrupt. All overlay code transfers are made through xe "Vectoring"vectored calls. What is the level of granularity for swapping overlays in and out of the overlay pool? WarpLink swaps xe "Overlays:Granularity"overlays into and out of the overlay pool at the segment level. For xe "Clipper:Overlay memory usage"Clipper and xe "Clarion:Overlay memory usage"Clarion users this means at the function and procedure level. For other languages this usually means at the module level. Overlays take a minimum of 512 bytes in the overlay pool regardless of size because memory from the overlay pool is allocated to the overlay in 512-byte increments. What type of code should not be overlaid? Do not overlay any .OBJ or .LIB module which contains interrupt handlers. Do not xe "Overlays:Do not overlay code"overlay self-modifying code unless the code modifications are only used before calling another overlaid or root module. The modifications will be lost if the overlay is swapped out or reloaded. Do not overlay modules which call other modules via an xe "Overlaying:Indirect near calls"indirect near call. (Near calls within an overlaid module are not a problem.) You can overlay modules which call other modules via a xe "Overlaying:Direct near calls"direct near call if you use xe "Brackets"brackets instead of parentheses to specify an overlay (small model code overlaying). Refer to Chapter 18, Other WarpLink Features, for a discussion of overlaying small model code. Do not place the program xe "Startup code"startup code in an overlay. The program must have a starting address that is not overlaid. Some languages (Borland C, for example) have startup code in an object module, while others (Clipper, for example) have their startup code in a library module. It is recommended that you do not overlay code that is very small or which is frequently called. Code that is called several hundred times a second or more throughout the program can affect your program's operating speed if it is overlaid due to overlay manager overhead. Conserving Memory How can I use less xe "Memory:Conserving"memory in my program? Overlay as much of your program code as possible provided it does not significantly affect your program's operating efficiency. The WarpSpeed profiler is a valuable tool for determining which code may called too often to overlay, or when you should consider increasing the overlay pool size to increase operation speed. Use .LIB files for code that may not always be used by the program being created. Do not use .OBJ files in such cases because all code and data in .OBJ files are placed within the executable program, whether the program needs it or not. For example, if your programs has an .OBJ file containing a 3K function or procedure that it never uses, that 3K function or procedure will still get linked into your program. .LIB files are different. WarpLink will link in only the modules the program needs if they are contained within a .LIB file. If the same 3K function or procedure were in its own module and added to a .LIB file, even if the .LIB was specified on the linker command line, the function or procedure would not be linked into the program. Speeding Up Link Times How do I xe "Linking:Speed"speed up the link process? Do not use the /m (create map file) or /mx (create expanded map file) options unnecessarily. These options create another, possibly large, file that may slow the link process. Copy your .LIB files to a RAM disk and using the LIB environment variable to point to their new location. Use the TMP environment variable to point to a RAM disk for temporary files. Displaying link processing information, by using the /i option, when there are many files to process may slow link speed. Linking with external overlays is slightly faster than linking with internal overlays since WarpLink must copy the internal overlay file to the end of the EXE file when link processing is complete. Finally and most importantly, be sure to use the /xp, /xt, /ql, and Clipper incremental link options where possible in order to really speed things along. Linker Response Files How do I put comments in a response file? xe "Comments"Comments in a xe "Response files:Comments"response file are denoted by a '#' in the first column of a line. Putting a '#' in a different column will result in an error since WarpLink will attempt to interpret it as a file name or option. Can I nest response files inside another? No, you cannot nest xe "Response files:Nesting"response files. However, you can use more than one response file at a time by listing them one after another on the DOS command line (or in a batch file). You may also load more than one response file at a time using Interactive WarpLink to build a larger response file containing all the information of its component response files. See Also Refer to Chapter 3, Response Files, for more information. Feedback Messages WarpLink gave warning messages about the program while linking. Can I still use my program? xe "Warnings:File creating"Warnings do not stop creation of an .EXE or .COM file, nor do they always indicate a problem in the file created. Warnings indicate that the linker has encountered an unusual situation which may lead to a problem when operating the linked program. WarpLink provides a detailed message describing the situation with the warning in case you need to make a correction. Sometimes a correction is unnecessary or undesirable. For example, third party libraries may cause benign duplicate symbol warnings when linking that can be safely ignored. You do not need to be concerned with these messages as long as you understand why the warning occurs. WarpLink gives xe "Warnings:Turning off"warning messages on situations that are not a problem for my program. Can I turn them off? Yes you can, by using the /wn option. However, be aware that any new linker warnings that may occur while developing your program will not be displayed either. If you have problems with your program and have the /wn option set, remove it and relink in case a new warning message is present. PRIVATE Chapter 21. tc \l 1 "Chapter 21. " xe "Troubleshooting and problem-solving"Troubleshooting and Problem-Solving  This chapter provides an explanation of the most common warning or error messages that you may encounter while using WarpLink. Error and xe "Warnings:Messages"Warning xe "Error:Messages"Messages Bad COM file format, program has invalid entry point: Either the /c option (create .COM file) was used inappropriately, the assembly language source is missing the ORG 100h statement, or the ORG 100h came after code or data was defined in the program. Bad COM file format. Program has segment fixups: Either this file is supposed to be an .EXE program, or the program contains a pseudo-op such as DD or @Data that requires segment-relative information to be calculated by the linker. This is not valid for use in .COM programs. Bad COM file format. Program has stack segment: Either this file is supposed to be an .EXE program or the .Stack directive appeared in a .COM program. .COM programs cannot have a .Stack directive. The program must manipulate the stack pointer directly. Bad COM file format. Program larger than 64K: This happens on those rare occasions where a .COM program gets too big or the /c option was used on an .EXE file that somehow passed as a .COM file. Either reduce your code size or recompile using a larger memory model and remove the /c option to create an .EXE file. DOS could not find a file needed by WarpLink: A specified file could not be found on the current directory or on the path. Make sure you have used the correct spelling, drive letter, or path specification. Another possibility is that an .OBJ file was not created at all due to a compiler error. This message will also appear if you do not specify your link file extension when using response files. Externally declared symbol has no public definition: This message usually appears when a needed .OBJ or .LIB file was not specified on the command line, or when the name of a function or procedure has been misspelled in a program. The linker cannot find a symbol needed by the program. File access denied: Some sort of network or DOS error, such as application of read-only status to a file that should be disposable (such as an old .OBJ file) has taken place. Fixup overflow: The most common cause of fixup overflows is when you are coding in a high-level language, switch memory models in midstream, and forget to delete old .OBJ files. Linking small with large model code when you did not plan for it can cause this message to appear. Another cause could be when an intersegment short (or near) jump (or call) is made in assembly language. Invalid WarpLink option: An invalid option or option setting was passed to WarpLink either at the DOS prompt or through a response file. Refer to Chapter 6, WarpLink Options, for a complete description of all valid WarpLink options and their allowed values. This error most often occurs when using improper spacing between options names. Separate options from other options and file names with a space or plus character (+). Length of response file line exceeded 127 characters: There is no limit to the size of response files. However the length of any particular line in the file cannot be longer than 127 characters. Make sure the text editor used to create the response file terminates each line with a carriage return/linefeed. Nested parentheses in link syntax: Look for extra parentheses. Check the overlay specifications and remove the offending parentheses. No object modules specified in link syntax: There is no .OBJ file listed, but the command includes at least one of the following: .MAP file name, executable name, or .LIB name. No stack segment was found for the EXE file: This warning is most often caused when the /c option was omitted when linking a tiny model assembly program. An .EXE file must set up its own stack. Although it may seem to work at times, the program will assuredly fail if the .Stack directive is not used. Not enough memory to operate WarpLink: WarpLink needs about 250K to operate, more for larger programs. Use of the /sp option requires a good deal more memory than usual because Clipper symbol table information is kept in memory. Segment size exceeds 64K: This fatal error is most often caused by using the wrong memory model or trying to place too much static data in a program. The program attempted to place too much data or code in a single segment. Segments cannot be larger than 65535 bytes in size. Symbol has more than one public definition: This situation occurs in a program that has two or more globally visible symbols with the same name. Renaming one of the symbols may solve this problem. Check for two or more listings of an object module in the object module list. The first definition of the symbol has precedence over any definitions which may follow. Too many open files or handles: Change the FILES= statement in your CONFIG.SYS file to allow more files to be open at one time. Unexpected end of file: The file ended before the end of a record was reached. This is usually due to file truncation caused by DOS error or system reset. Recreate the module and relink. Explanation Of Common Problems In addition to the previous error and warning message explanations, the steps suggested below may help you resolve the following xe "Problem conditions"problem conditions: Clipper 5 debugger CLD.EXE does not work: Do not use the runtime EMS or XMS options (/ox, /ohp, /oht, /orp, /ort, /ou) with Clipper 5's debugger. Turn these options off with WarpMod before running the debugger. Turn them on with WarpMod when you are finished using the debugger. Intermittent or erratic program runtime problems when using the /ox option: Use the SET CLIPPER=BADCACHE setting when using Clipper 5. Use the SET CLIPPER=E0 setting (turn off Clipper's use of EMS) when using Clipper Summer '87. Make file utility terminates on WarpLink warning: Use the /w0 option to cause WarpLink to return codes of zero for nonfatal warning messages. No program speed increase when using the /ox and /ohp options, even though there is significant free EMS memory present: The overlay manager has probably detected LIM EMS version 3.0 or 3.2 memory on the machine being used. For the /ox and /ohp options to work together, use LIM EMS 4.0. Program size increase when using /ql option: Erase the old .QLK file and let WarpLink rebuild a new file. Internal errors when using /ql option: Make sure that the /ql option is placed before the library list. Do not use the /ql option if you use direct library modules in the object file list and the EXE name is different from the first object file name. If the problem persists, try deleting the .QLK file and relinking. Internal errors when using /clpi option: Make sure the /clpi option is placed before the library list. Internal errors when using /clp5 option: Make sure the /clp5 option is placed before the library list and that CLIPPER.LIB is explicitly listed in the library list. xe "Problem conditions"Problem overlaying QuickBASIC files: The main xe "QuickBASIC:Overlaying"QuickBASIC module containing the initial code executed upon program startup cannot be overlaid. You must place this module in the root. For this reason, you should either make the main module very small or place in it routines you do not wish to overlay. Files compiled with versions of QuickBASIC prior to 4.0 cannot be overlaid. PRIVATE Chapter 22. tc \l 1 "Chapter 22. " Warplink xe "Technical support"Technical Support  As a registered WarpLink owner, you may contact WarpLink technical support for help with any WarpLink-related problems that you cannot solve on your own. Getting xe "Help:Getting"Help Before contacting technical support, please read the Chapter 20, Common WarpLink Questions and Answers, and Chapter 21, Troubleshooting and Problem-Solving. The answer to your problem may be there, saving you the time and effort involved in contacting WarpLink technical support. There is no support for this free version of WarpLink other than that listed in the file documentation. xe "Overlay manager:setjmp()/longjmp() "Setjmp()/longjmp() Support xe "Debugging version"Debugging Overlay Manager Versions A debugging version of the Warplink overlay managers may be available for use in extreme problem cases. This version saves the overlay manager state when a program fails. The technical information stored in the data files created by the overlay manager must be interpreted by WarpLink technical support. Before using a debugging version, you must work with WarpLink technical support to eliminate all other possible causes for your problem. The debugging versions affect the performance of the overlaid program, are quite complex, and require extensive time and effort to transfer and interpret data files. xe "Custom development"Custom xe "Development and distribution:Custom"Development and Distribution Devore Software & Consulting performs custom development and testing of linkers and overlay managers for use in such areas as ROM-based systems, custom-designed error handlers, program debugging, and overlaid programmable interfaces. If you have a situation that requires linking or overlay management expertise, we may be able to help. Special version, reduced-feature, or customized copies of WarpLink are available for bundling arrangements with vendors who wish to include a linker with their products. PRIVATE Indextc \l 1 "Index"  index \e ' '.COM file 3 .DBF file 65, 66 .EXE file 3, 26 .ILF files 24 .LIB file 3 .MAP file 3 .OBJ file 3 .OVL file name 36 .QLK file 46 .WSP file 59 .WSS file 65 $$_COM_END variable 107 $$_EXE_IMAGE_SIZE variable 107, 108 _OM_FREE_EMS 45 _OVLMGR_FREE_EMS 45 386^Max 36, 5153 A America OnLine 125 B BBS 125 Brackets 17, 60, 65, 81, 110, 111, 117, 118 C Clarion /dm link option 29 /oc option 32 /op:m option 113 /orp option 40 /ort option 40 and DDLs 105 Buffer procedures 115 CNDDLMGR.DAT 29 Interactive WarpLink 78 Linking example 7 Overlay IDLE procedures 56 Overlaying 56, 114, 117 Overlay memory usage 118 OVL_SWAP 55 Passing pointers 114 Profiler 56, 59 Swap file 55 Symbol case 48 Using EMS 56 Using XMS 56 Clarion 2.1 55 Clarion overlays 23 Clipper .CLP files 28 /dm link option 28 /ohp option 34 /ohp3 35 /oht 36 and DDLs 105 BADCACHE setting 45 Code as data 47 DBU program 6 E0 setting 45 Incremental linking 25 Interactive WarpLink 78 Overlay memory usage 118 Symbol case 48 Symbol table compaction 49 Clipper 5 /dm link option 29 C5DDLMGR.DAT 29 CLD.EXE and options 34, 35, 36, 40, 43, 45 Interactive WarpLink 78 CLIPPER.LIB 23, 78 Comments 8, 120 Common questions and answers 117 CompuServe 125 Custom development 126 D Dformat Dynamic Libraries (DDLs) 99 DDL options /ddl 101 /dm 101 /udl 101 DDLMGR.DAT 28 DDLs Benefits of using 104 Clipper symbol table compaction 105 Command options 102 DDLPATH environment variable 103 Elective modules 100 EMS use 99 Master 50, 99 Options Summary 100 Overlays 102, 104 Required modules 100 Runtime Operation 103 Support 99 Support files 50 Terminology 99 XMS use 99 Debugging version 126 Default libraries 31 Development and distribution Custom 126 Direct library module specification 46, 97 DOS And UMB 42 ERRORLEVEL 51 Return code 51 DOSSEG 27 E EMS 52, 53 3.0 33, 34, 39 4.0 33, 34, 39 Allocation 32, 33, 39, 45 Compatibility 45 Linktime use 51 Overlay stashing 32 Page frame 34, 44 Environment variable DDLPATH 13, 103 LIB 11 OBJ 12, 28 OVL_SWAP 13 TMP 12 WARPLINK 13 Environment variables List of 11 Error DOS 86 Handlers 109 Messages 70, 72, 80, 84, 121 Out of memory 22 Expert Help 95 Extended dictionary 29 Extraction 97 F File extensions .DBF 66 .WSS 65, 66 Default 4 Functions SmartMem 88 G GEnie 125 H Help Expert 95 Getting 125 I Incremental linking 24 Padding 26 Indexing 29 Informational Messages 80, 83 Interactive WarpLink 8, 75 Internet 125 L Libraries Borland library 29 Extended dictionary 29 Overlaying 117 Library Direct library module specification 97 Module extraction 97 Library file 3 License Agreement SmartMem 87 WarpLink ii Link file 81 Link Files Converting 81 Link options /as 21 /b 22 /c 22 /cla 23, 47 /clp5 23 /clpf 24 /clpi 24, 26, 98 /clpp 26 /clps 26 /d 27 /ddl 28 /dm 28 /em 29 /i 30, 36 /m 30 /mx 30 /nd 31 /oc 31 /ohp 32, 44 /ohp3 34, 44 /oht 33, 35 /ol 37 /on 36, 37 /op 38, 44 /op:m 39, 113 /orp 33, 39, 40 /ort 35, 39, 40 /os 41, 49 /ou 42, 44 /ox 33, 34, 42, 43 /ql 46, 98 /r 23, 39, 47, 110 /s 48 /sp 25, 49 /st 41, 49 /tf 50 /udl 50 /w0 51 /wn 51 /xp 5153 /xt 51, 52 Nonoverlay options summary 19 Overlay options summary 20 Linking Incremental linking with Clipper 25 Speed 98, 119 Using response file 5 M Map files Contents 30 Use of 3 Memory /sp affecting 49 Conserving 37, 41, 46, 49, 83, 115, 119 Menu Dropdown 76 Edit 77 Environment 78 File 76 Link 77 Project 77 Messages Informational 80, 83 Microsoft Link /CP 22 /CPARMAXALLOC 22 /NOE 29 /NOEXTENDEDDICTIONARY 29 Map files 30 MSDOS 5.0 42 And UMBs 42 N Norton Guides help system 95 O Object file 3 Options WarpConv 82 WarpLink 19 WSPRUN 61 WSPSTAT 65 Overlay Class name 31 Creating 117 Pool size 39 Small model code 110 Overlay file Link stash 51, 52 Name 37 Overlay manager Error handlers 109 Internal stack 41 Internal tables 37 setjmp()/longjmp() 126 With DDLs 103 Overlay pool Defined 117 Size 39 Sizes below minimum required 113 Overlaying Direct near calls 110, 118 Indirect near calls 110, 118 Overlays .COM files 22 Do not overlay code 118 Dynamic 15 Granularity 118 Internal 36 Multiple overlay files 117 Overlay manager interrupt 118 Performance 16 Root 15 Root calls 110 Small model code 110 Static 15, 118 Using 15 OVL_SWAP Environment variable 55 P Parentheses 3, 6, 7, 15, 102, 110, 117 Problem conditions 123, 124 Profiler Interrupt handler 69 Memory use 69 Selfmodifying code 69 Speed 69 Q QEMM 36, 5153 Questions and answers 117 QuickBASIC Overlaying 124 QuickLinker option 46 R Response files 5, 13, 19, 81, 82 Command line options 6Comments 8, 120 Creating overlays 117 Linking with 5 Merging 8 Multiple lines 8 Nesting 120 Using multiple files 7, 8 Return policy ii Root Calling overlays 48 Defined 15 S Script files 81 Segment ordering DOSSEG 27 Segments Class name 31 Shortcut keys 76 Small model code 104, 110 SmartMem Functions Summary 88 SMARTMEM.XXX file 27 SmartMem functions _rept() 92 h_free_mem 89 h_graph() 89 h_graphs() 90 h_hotkey() 90 h_maxblock() 91 h_memory() 91 h_pack() 92 h_tot_mem() 93 h_used_mem() 93 h_walk() 94 SmartMem Functions for Clipper Summer '87 87 SP.EXE 83 Error messages 84 Examples 86 Informational messages 83 Stack Size 49 Startup code 118 Symbol Table Compaction Utility SP.EXE 83 Symbols Case sensitive 48 T Technical support 125 Temporary file EMS 50 Link stash 51, 52 Naming 50 XMS 50 Troubleshooting and problemsolving 121 U UMB Allocation 42 V Vectoring 110, 118 W Warning Externally declared symbol has no public definition 48 Symbol has more than one public definition 48 Warnings Displaying 51 File creating 120 Messages 121 Turning off 120 WarpConv 81 Options Summary 82 WarpConv Options /nc 82 /no 82 /nw 82 WarpHog 79 Error Messages 80 Messages 80 WarpLink Interactive 75 Internal errors 47 Options 19 WarpMod 57 Distribution 58 Monochrome monitors 58 WarpSpeed Profiler 59 Warranty ii WSPRUN Error messages 70 Options summary 61 Using 59 WSPRUN options /a 61 /if 62 /im 62 /is 62 /l 62 /m 63 /n 63 /o 63 /s 63 /u 63, 64 /w 64 /xf 64 /xm 64 /xs 64 /y 64 WSPSTAT Error messages 72 Options summary 65 WSPSTAT options /a 66 /c 66 /d 66 /lm 67 /m 67 /n 68 /o 68, 69 /p 68, 69 /pl 68 /sa 68 /sc 68 /su 68 /t 69 /u 69 /z 69 WSPSTAT options summary 65 X XMS 52, 53 Allocation 35, 40, 42 Linktime use 52 Overlay stashing 35   page \* romanii page \* romani page \* arabic2 WarpLink -- The Dynamic Overlay Linker Chapter 1. Introduction page \* arabic1 page \* arabic4 WarpLink -- The Dynamic Overlay Linker Chapter 2. Using WarpLink page \* arabic3 page \* arabic10 WarpLink -- The Dynamic Overlay Linker Chapter 3. Response Files page \* arabic9 page \* arabic14 WarpLink -- The Dynamic Overlay Linker Chapter 4. Environment Variables page \* arabic13 page \* arabic18 WarpLink -- The Dynamic Overlay Linker Chapter 5. Using Overlays page \* arabic17 page \* arabic26 WarpLink -- The Dynamic Overlay Linker Chapter 6. WarpLink Options page \* arabic27 page \* arabic56 WarpLink -- The Dynamic Overlay Linker Chapter 7. Using WarpLink with Clarion 2.1 page \* arabic55 page \* arabic58 WarpLink -- The Dynamic Overlay Linker Chapter 8. WarpMod Utility page \* arabic57 page \* arabic74 WarpLink -- The Dynamic Overlay Linker Chapter 9. WarpSpeed Profiler page \* arabic75 page \* arabic78 WarpLink -- The Dynamic Overlay Linker Chapter 10. Interactive WarpLink Utility page \* arabic79 page \* arabic80 WarpLink -- The Dynamic Overlay Linker Chapter 11. WarpHog Utility page \* arabic81 page \* arabic82 WarpLink -- The Dynamic Overlay Linker Chapter 12. WarpConv Utility page \* arabic83 page \* arabic86 WarpLink -- The Dynamic Overlay Linker Chapter 13. Clipper Symbol Table Compaction Utility page \* arabic87 page \* arabic88 WarpLink -- The Dynamic Overlay Linker Chapter 15. Norton Guides Help System page \* arabic89 page \* arabic96 WarpLink -- The Dynamic Overlay Linker Chapter 16. Direct Library Module Specification page \* arabic97 page \* arabic98 WarpLink -- The Dynamic Overlay Linker Chapter 17. Using D-format Dynamic Libraries page \* arabic99 page \* arabic106 WarpLink -- The Dynamic Overlay Linker Chapter 18. Other WarpLink Features page \* arabic107 page \* arabic112 WarpLink -- The Dynamic Overlay Linker Chapter 19. Using Overlay Pool Sizes Below Minimum Required page \* arabic113 page \* arabic116 WarpLink -- The Dynamic Overlay Linker Chapter 20. Common Questions and Answers About WarpLink page \* arabic117 page \* arabic120 WarpLink -- The Dynamic Overlay Linker Chapter 21. Troubleshooting and Problem-Solving page \* arabic121 page \* arabic124 WarpLink -- The Dynamic Overlay Linker Index page \* arabic131 !"-.;<()9:&/|] a     " # 9 : G ˸˲˩˲˲˲˩˛Ûj5CJOJQJU5CJ$OJQJj5CJ$OJQJUjOJQJU 5OJQJjUhmHnH5CJ$OJQJOJQJCJOJQJ5CJOJQJj5CJOJQJU CJOJQJ5CJOJQJ2  "#$%=>; *$ `0*$d*$;Wu%&0OqQ{| \ ] b  ; H J K ] ^   ? @ . / %&~ab./()9:}~( ) ""@#$$H&I&J&Z&d;Wu%&0OqQ{| \ ] b *$ `0 *$h !   ; H J K ] ^   ? @ . / *$h `0*$d `0 *$ `0 *$h ! G H I K \ )8~ -< ,z{FGUVڸڸ OJQJjOJQJU 6OJQJ6CJOJQJ CJOJQJ 5OJQJ5CJ$OJQJjS5CJOJQJU5CJ$OJQJj5CJ$OJQJU5CJOJQJjUhmHnHOJQJ7/ %&~ab./*$d `0 *$ `0*$h `0()9:}~( ) ""@#$$H&I&J&Z&[&j'k'' *$ `01 9 -!.!C!D!!! " "#"0"L"M"^"_"##$#%#$$%%J&Y&&&&&9':'V'W''''''l)r)))))))))))) *꺰5CJ$OJQJj5CJOJQJU5CJ$OJQJj5CJ$OJQJUjCJOJQJU5CJOJQJ 5OJQJ 6OJQJOJQJ OJQJjOJQJUB>u>v>? *$ `00:6:@:A:i:j:<<<<9=Z=====B>v>@A@v@@@@@@AA+A,A5A6ARASAA B!B/B0BRBSBaBCCCCCCCCCCC D D[EFFFF5CJ$OJQJj5CJ$OJQJU5CJOJQJj5CJOJQJU5CJOJQJ 6OJQJ CJOJQJ OJQJjOJQJUOJQJ 5OJQJ:8=9=Y=Z=========A>B>u>v>?@@@@A@u@v@@@ B!BbBcBBCCC`CCCCCCCCCCEZE[EyE{EEEEEEF F-FQFhFjFlFnFFFFFFFFFFFFFFGssssssttttQuRuuubvcvdvvvvvvvwww$w%wd?@@@@A@u@v@@@ B!BbBcBBCCC`CCCCCCCCCCEZE[EyE *$ `0yE{EEEEEEF F-FQFhFjFlFnFFFFFFFFFFFFFFG *$ `0FFFGGGG2G3G4GSGTGvGwGGGGGGGGGHH H!HBH^HhHiHHH`J|JJJKKddd*$ `0p*$d `0p *$ `0pr^y^^^^^^!`4`aa$a%aaa9c:cLcNc_c`cdccc1dCddd;eMeUeVeoepemmmmmmmn o oo ppprrss_ssssssss5CJ$OJQJj5CJOJQJU5CJ$OJQJj5CJ$OJQJU 6OJQJ CJOJQJ OJQJ5CJOJQJ5OJQJjOJQJUOJQJ 5OJQJ;d9e:e;eNeOehhllmmm+o,oqprpppTqUqrrssss *$ `0p*$ `0psssssssssssssttttttttRuudvpvqvvvvvvvvvvvvvvvvvvw w0w1wIwJw`wľľľڶگڶľăڃ}ڃڃڃڃڃ 6OJQJ 5OJQJjGCJOJQJU5CJOJQJj5CJOJQJU CJOJQJ5CJOJQJ OJQJjOJQJUjUhmHnHOJQJ5CJ$OJQJ5CJ$OJQJj5CJ$OJQJU1ssssttttQuRuuubvcvdvvvvvvv $$x0Y !*$Z6$ `0p*$d `0p *$ `0pvwww$w%w(w:w;wAwzw{wwwwwwww'x(x̀X $$x0Y ! $$x0Y !*$Z6$ `0p%w(w:w;wAwzw{wwwwwwww'x(x+xHxIxNxoxpxyxxxxxxxxxyyyy&y'y+yMyNyRypyqyuyyyyyyyyyy z zz,z-z7zfzgzkzzzzzzzzzz { { {{{R{S{e{q{r{w{{{{{{{"|#|0|t|u||||| } }}5}d`wbwcwdwwwwwwwwwwwwwwwwwxxxx/x0xUxVx^x_xfxgxtxxx}x~xxxxxxxxxxyyyyy2y3yAdist !67U]gΌόՎێ!,-DEvX\ГѓٓړۓjCJOJQJUjECJOJQJU 6OJQJ 5OJQJOJQJjCJOJQJU OJQJjOJQJUGދߋTUӎԎՎuv-.u$$x! *$Z6$ h*$ `0p *$ `0p.uvRSΓϓГwxЕѕҕ gh'(?@A_`ԦզZ[©.bϭ <?Ԯծ֮GHduvRSΓϓГwxЕѕҕ gh$$x! *$Z6$ h*$ `0p *$ `0p#./FGxҕӕەܕݕ67hsИјљҙ78MNZ`7;ŢȢ?ABJKLSW]_`a~ 6OJQJjDCJOJQJU CJOJQJjCJOJQJU OJQJjOJQJU 5OJQJOJQJJ'(?@A*$ `0p *$ `0pA_`ԦզZ[©*$ `0Fp*$ `0p *$ `0p$$x! *$Z6$ h ()`k"#©é˩̩ͩ٩۩ܩݩƪǪȪѪҪ01<=DEab¬/0cdҭӭ!" jOJQJjCJOJQJUjCJOJQJU OJQJjOJQJUOJQJ 5OJQJH.bϭ <? *$ `0p$$x! *$Z6$ h*$ `0pîĮˮ̮֮HPZ±űƱ߱!"78ӲԲ۵ܵ߶.0LM TmnjCJOJQJU 6OJQJ OJQJ 5OJQJOJQJjOJQJUjCCJOJQJULԮծ֮GHݱޱ߱óij*$ `0p *$ `0p$$x! *$Z6$ hݱޱ߱óij޶߶ klmtu ľžpqrWXYrs89fgpijk+,KL'(d޶߶ klmtu ľž$$x! *$Z6$ h *$ `0p*$ `0pnvwxĸHIklop{./ļżBCžƾξϾо-.mnFGjCJOJQJUjBCJOJQJU 5OJQJOJQJjOJQJUjCJOJQJU OJQJIpqr$$x! *$Z6$ h*$ `0p *$ `0pGders{|} qrYZbcdlprsz{ճ 6OJQJjCJOJQJUjACJOJQJU 5OJQJjCJOJQJUOJQJjOJQJU OJQJFWXYrs89 *$Z6$ h*$ `0p *$ `0p$$x!gy}kltuv,7PQjk|}>?RSBCYZ45no{|23 6OJQJjCJOJQJU OJQJjOJQJU CJOJQJ 5OJQJOJQJOfgpijk+,KL'($$x! *$Z6$ h*$ `0p *$ `0p(z{IJ PQZABCg ABK~7878BGH012      j k m     dz{IJ $$x! *$Z6$ h*$ `0p *$ `0p378PQ)*JM '+{MNZ[wzVWjkQcCDLMNj CJOJQJU 6OJQJj@ CJOJQJU OJQJjOJQJU 5OJQJOJQJL PQZABCg AB$$x! *$Z6$ h *$ `0p*$ `0pNW[]^ijtu&'@A*+AB34 BTyzghqr{|vwklj CJOJQJU OJQJjOJQJU 5OJQJ 6OJQJOJQJRBK~78$$x! *$Z6$ h*$ `0p *$ `0p$%:;8FKLbc# !"89HSXYnoQS23;<j CJOJQJUj CJOJQJU 5OJQJ 6OJQJj? CJOJQJU OJQJOJQJjOJQJUG78BGH012  $$x! *$Z6$ h *$ `0p*$ `0p<=EIKLSTpq   > A N h m n v w x             ())C  )*56JK[fkl^_j CJOJQJUj> CJOJQJU OJQJ 5OJQJ 6OJQJOJQJjOJQJUL     j k m        YZ[)$$x! *$Z6$ h *$ `0p*$ `0p    YZ[)*!"Zc;<=01!!W"X"}#~##Z%[%D&/)0)1)r)s)t)**B,C,a.b.l.c0d0111r2s2t2222v3w3555776899::f<g<<<-@.@FBGBPB4Cd_rs9:FHTUWXno"*Zl#QRjk,-=HMNde@ATU()IL 6OJQJj= CJOJQJUj CJOJQJU 5OJQJOJQJjOJQJU OJQJL)*!"Zc;<=$$x! *$Z6$ h*$ `0p *$ `0p01!!W"X"}#~##Z%[%D&/)$$x! *$Z6$ h*$ `0p *$ `0p1<ABWX!!/#0#E#F#~######c%d%%%1)2):);)<)H)I)X)Y)t))))))"*#*3*4*o,p,,,b.q.r.s.........////11111122t2u2}2j CJOJQJU OJQJjOJQJU 6OJQJ 5OJQJOJQJO/)0)1)r)s)t)**B,C,a.b.l.c0d0111r2s2t222*$ `0p$$x! *$Z6$ h *$ `0p}2~222222222222556 666*7/788::::<<<<<<<===S=T=>> ? ?T@U@j@k@GBTBpBqBBBBBBB5CDCJCKCaCbCDDDD^GpGGGGGGGGG_H`HHHHH I I OJQJ 5OJQJ 6OJQJOJQJjOJQJUj CJOJQJUR22v3w3555776899::f<g<<<-@.@FBGBPB4C5C?CjD*$ `0p *$ `0p4C5C?CjDkD]G^GgG I I I7I8I9IIIlKmKLL>O?O:Q;QRTTTTUU:U;UVVfVgVhVWWYYmZnZvZZ [^^^H^I^J^=`>`cadabbbccc?c@cddffffffggghohphiijjjjjj\k]kll~mmmZn[nnn-o.o/odjDkD]G^GgG I I I7I8I9IIIlKmKLL>O?O:Q;QRT$$x! *$Z6$ h*$ `0p *$ `0p IIII%I&I*I+I9IDIJIKI`IaIJJJJNJOJfJgJKKLL M!MxPyPPP8S`cadabbbccc?c@cddfff*$ `0p$$x! *$Z6$ h *$ `0p^ ^!^+^,^J^U^n^o^^^^^^^^^^^8_E_J_O_____N`O``````aaaaaa%bbbbbbbbbbc c@cKcddddddee@eAeZe[epeqeeefffտj;CJOJQJU5OJQJ OJQJ 5OJQJOJQJjOJQJUj CJOJQJUHffffffffffg!g'g(g=g>gShnhhhhhiiiiiijjjjjjjjjjjjjj]khknkokkkkkkk l lmmmmmmnnnnnnnnno oϳj:CJOJQJUjCJOJQJU OJQJ 5OJQJ 6OJQJOJQJjOJQJUjCJOJQJUFffffggghohphiijjjjjj\k]kll~m*$ `0p *$ `0p$$x! *$Z6$ h~mmmZn[nnn-o.o/oWoXoppqq)r*r4rYsZs[ss$$x! *$Z6$ h*$ `0p *$ `0p ooo/o5o:oXocohoiooooooo`qdqqqqq*r8r=r>rUrVrhrkr[s\sdsesfspsqsssssssssssssftgtzt{tuuuuuuuuuuuuuuuvvvvhwkwwwwjCJOJQJUjCJOJQJU OJQJjOJQJU 6OJQJ 5OJQJOJQJL/oWoXoppqq)r*r4rYsZs[ssssuuuuuuMwNwwwwwwwxxzzm~n~CDdxÀĀπҀր׀؀<=>XY҄ӄՅօćŇ (+/0<@DEPSWXYc@BqdsssuuuuuuMwNwwwwwwwxxzzm~n~ *$Z6$ h*$ `0p *$ `0p$$x!wwwwwwwww x xLyMyjykyyyyy {{#{${8{9{B{C{K{L{X{Y{}{~{{{~~~~~~~~DEMNOcdwx؀+,45=>SU]^rs|} jCJOJQJU OJQJ 5OJQJOJQJjOJQJUj9CJOJQJUKn~CDdxDtD-$$TxF <-$$TxF <*$Z6$ `0p *$ `0p*$ `0p ÀĀπҀր׀؀TLt*$ `0p *$ `0p-$$TxF <*$Z6$ `0p-$$TxF < >INOde|}Ђт #$  RS[\demnŇƇ·χЇ YgBCKLMXYopṯ5CJ$OJQJj5CJOJQJU5CJ$OJQJj5CJ$OJQJUj8CJOJQJU OJQJ 5OJQJOJQJjOJQJUjCJOJQJU;<=>XY҄ӄՅօćŇ *$Z6$ `0p*$ `0p *$ `0p$$x! *$Z6$ h (+/0<@DDeT-$$TxF <-$$TxF <*$Z6$ `0p-$$TxF < @DEPSWXYc@BqLtt*$ `0p *$ `0p-$$TxF <-$$TxF <*$Z6$ `0p p  Ջߋtِڐ+0345YZ͕Ε!;<?͘Θ08B}򴪚j5CJOJQJU5CJ$OJQJj5CJ$OJQJU 6OJQJ 5OJQJ5CJOJQJ OJQJjOJQJUjUhmHnHOJQJ5CJ$OJQJ<ԋՋst,-   !< *$ `0p*$d `0pԋՋst,-   !<=/0™TU~34ՠ23RSġ8Ut*+S¤BCZ|/X,-IJd<=/0™TU~*$d `0p*$ `0p *$ `0pƙǙәԙU^jm|7:֠3STġš89UVtu+,EFW  ¤äǿǿ򥝥j5CJ$OJQJU5OJQJj5OJQJU jOJQJ 5OJQJ6CJOJQJ CJOJQJ5CJOJQJ OJQJjOJQJUjUhmHnHOJQJ5CJ$OJQJ834ՠ23RSġ8Ut*+S*$ `0Fp *$ `0pS¤BCZ|/X*$d `0Fp*$ `0Fp*$ `0Fpäˤ̤ͤؤ٤ CDZ[|}/0XY-H«׫٫./@A@AOPǭȭ 0=?G˵˧˧˧˧˧˧˧˧˧˟˵˵˵˧˧˧˟˟˘ CJOJQJ5CJOJQJ jOJQJ OJQJjOJQJUjUhmHnHOJQJ5CJ$OJQJj5CJ$OJQJUj35CJOJQJU5CJ$OJQJ<,-IJ-.[\ǭOPab  :*$F `0Fp*$ `0FpJ-.[\ǭOPab  :./0>?mne´δϴ״56Awxɵʵյ458Z[^-.9dehԷշַRSCD¹d./0>?mne´δϴ״ $$x0! $$x0!*$Z6$ `0Fp*$ `0FpGNPW_hnDKz29fg´ʹҴִߴ:@ABTU|ƸڠjCJOJQJU5CJOJQJj5CJOJQJU5CJOJQJ 6OJQJ 5OJQJ OJQJjOJQJUOJQJ CJOJQJ6CJOJQJ?56Awxɵʵյ458Z[lːˈ˔˘˼ $$x0!*$Z6$ `0Fp͵Ե޵ߵ=>klʶ˶  28:;ABַܷS^de{|  "#IOQRdeֺj0CJOJQJUjCJOJQJU OJQJjOJQJU5CJOJQJ 6OJQJ 5OJQJOJQJI[^-.9dehː˄ $$x0! $$x0!*$Z6$ `0FpԷշַRSCD¹$$x!*$ `0Fp$$x! *$Z6$ h*$ `0Fpe¹ȹչֹ۹ܹ"#ºͺӺԺiqǼ,9\]tսֽ{|۾޻jCJOJQJUjCJOJQJU CJOJQJ OJQJjOJQJU 5OJQJ 6OJQJOJQJF¹ºhiǼ,89txy{$$x! *$Z6$ h*$ `0Fp*$ `0FpºhiǼ,89txy{ھ۾456fgijGQR~./>?@9IJz{ '(+dھ۾ *$Z6$ h*$ `0Fp*$ `0Fp$$x!Կտ  @EJO &'6<չի՝jCJOJQJUj.CJOJQJUjCJOJQJUjCJOJQJU OJQJ 5OJQJOJQJjOJQJUj/CJOJQJU>456fgij$$x!$$x! *$Z6$ h*$ `0Fp*$ `0Fp<Dgrxy ()*67HIxyHI*,CDGR~/089:@KQRhi:HJݺ5CJOJQJj-CJOJQJU CJOJQJjCJOJQJU OJQJjOJQJU 5OJQJOJQJ 6OJQJFGQR~.*$ `0Fp*$ `0Fp$$x! *$Z6$ h$$x!./>?@9IJz{ *$Z6$ `0Fp*$ `0Fp$$x! *$Z6$ h*$ `0FpJSZ\ckq{ QX(*89^_no =>\]~ὯůۡjCJOJQJUj5CJOJQJU5CJOJQJ5CJOJQJ 6OJQJ 5OJQJ OJQJjOJQJUOJQJ6CJOJQJ CJOJQJ? '(+XY\yzhh $$x09 $$x09*$Z6$ `0Fp $$x09+XY\yz*CDH_`d~DEF FGH{|} !&'/7<=%-.;=>GIJd#)56:;HIPQdewx'()56FQWXop  +,HSYZqr .1}~չj,CJOJQJUjCJOJQJU OJQJjOJQJU5CJOJQJ 6OJQJOJQJ 5OJQJH*CDH_`d~tː˔p||ː $$x09*$Z6$ `0FpDEFtߐz$$x! *$Z6$ h*$ `0Fp $$x09*$Z6$ `0Fp $$x09 F FGH{|}*$Z6$ `0Fp$$x! *$Z6$ h*$ `0Fp*$ `0FpHIbc $%,56>?@EKXY]^hnuqtչիۥ 6OJQJjCJOJQJUj+CJOJQJUjCJOJQJU OJQJ 5OJQJOJQJjOJQJUjCJOJQJU=LTdX-$$TxF) -$$TxF) *$Z6$ `0Fp-$$TxF)   !&'/7<=TXX-$$TxF) -$$TxF) *$Z6$ `0Fp=%-.;=>GIJ@0cD"$$Tx0("$$Tx0("$$Tx0(*$Z6$ `0Fp*$ `0Fp*$ `0Fp JXZ[ikl|~345fgh   YZ$%&MNO_`aGHIderseDEoVWdJXZ[ikl|~345DL*$ `0Fp*$ `0Fp"$$Tx0("$$Tx0(*$Z6$ `0Fp 5fgh   YZ*$ `0Fp*$ `0Fp$$x! *$Z6$ h/0 Zekl  &178OPOPXճեjCJOJQJUjCJOJQJU 6OJQJj*CJOJQJU OJQJ 5OJQJOJQJjOJQJUjCJOJQJU;$%&MNO_`a*$ `0Fp*$ `0Fp$$x! *$Z6$ hXYZ_erswx &'abjklrsz{,-&,-DEϳjCJOJQJUj~CJOJQJU OJQJ 5OJQJ 6OJQJOJQJjOJQJUj)CJOJQJUBG*$ `0Fp*$ `0Fp$$x! *$Z6$ h$$x!IJRSTUVmn<=PRjkPShk~fgEno濧j5CJOJQJU5CJOJQJ5CJOJQJj}CJOJQJU 5OJQJ OJQJOJQJjOJQJUj(CJOJQJU>GHIderse*$ `0Fp$$x! *$Z6$ h*$ `0FpDEoVW}Lef"#A!*$ `0Fp*$F `0FpWK"'f#@ q+cvw (5Q]y#,>Gq%.6mn5CJOJQJ5CJOJQJj5CJOJQJU 6OJQJOJQJ 5OJQJ56OJQJNW}Lef"#A! pqbc)Rz=>r$%7klm ?@^"#7ef/0X#Lt67d pqbc*$ `0Fp*$F `0Fp)Rz=>r$%7klm ?@^*$F `0Fp*$ `0Fp @]#6f0WX=T"/KWs%7@ZjkstuϿٷٷٷjOJQJUjUhmHnH5CJ$OJQJj5CJOJQJU5CJ$OJQJj5CJ$OJQJU56OJQJ 6OJQJ 5OJQJOJQJ="#7ef/0X*$F `0Fp*$ `0Fp#Lt67[ hj12*$d `0Fp*$F `0Fp*$ `0Fp7[ hj12IJKfg|}abrsTUvw  e f g h  / 0 8 ~      Z [   GH%&yz3412xy d26GJKebq !"01UYwz  f o h l       0 =       [ c  LSTUfg 5OJQJ6CJOJQJ CJOJQJ5CJOJQJ 6OJQJOJQJjOJQJU OJQJN2IJKfg|}abrsTUvw*$ `0Fp*$ `0Fp  e f g h  / 0 8 ~      Z [   *$ `0Fp*$ `0FpGH%&yz3412*$ `0Fp*$ `0Fpg&* /02:FZy$uv~YgƶЮЮЮ CJOJQJ5CJOJQJjUhmHnH5CJ$OJQJj%5CJOJQJU5CJ$OJQJj5CJ$OJQJU 6OJQJ OJQJjOJQJU 5OJQJOJQJ:xy tuWXYhi*$d `0Fp*$ `0Fp*$ `0FptuWXYhi !5 6 7 @ A z {      !!!(?(O(P((((()))))++`+a+l+++++++,, ,[,\,`,,,,,,,,d7 ? {            ! !!!;!(?(O(P((((()))))++`+a+l+++++*$Z6$ `0Fp*$ `0Fp*$ `0Fp+++++++++++#,$,9,:,c,d,s,t,,,,,,,,,,,,, -`-a-t-u-------.....%.&.I.T.....I/J/R/S/T/]/^/m/n//jCJOJQJUjuCJOJQJUj CJOJQJU5CJOJQJOJQJ 5OJQJjOJQJUjCJOJQJU OJQJ@+++,, ,[,\,`,,,k $$x0,  $$x0,  $$x0, *$Z6$ `0Fp $$x0,  ,,,,,,,,,---G.H.I.G/H/I////0*$ `0Fp$$x! *$Z6$ h*$ `0Fp,,,,---G.H.I.G/H/I////00011 1A3B3C3Q3R33333[5\5]555677,7777J8l888899 9`9a99::A:<;=;k;<<?<C=D=j= > >.>{??AABKBLBpB,C-CTCCCDgDhDDaEbE~EEEEEFFF'GHHH$Hd//:0;0T0U00000000000000111I1J1U1V13333C3P3333333B4I444]5^555˻ճճճ}s}5CJOJQJj5CJOJQJU 6OJQJ6CJOJQJ CJOJQJ5CJOJQJjUhmHnH5CJ$OJQJj5CJOJQJU5CJ$OJQJj5CJ$OJQJU OJQJjOJQJUOJQJ 5OJQJ-00011 1A3B3C3Q3R33333[5\5]55567*$F `0Fp*$d `0Fp*$ `0Fp*$ `0Fp55555555567+777K8k888 9!9;9<9B9C9V9W9_9a99:@:=;j;<><D=i= >->|??ABLBoB-CSCCDhDDcEgEhEvEwE}EEFF&GHHHH"HtHxH IIJJJj5CJ$OJQJU CJOJQJ 5OJQJOJQJ5CJOJQJj5CJOJQJU5CJOJQJH77,7777J8l888899 9`9a99::A:<;=;k;<<?<*$F `0Fp*$ `0Fp?<C=D=j= > >.>{??AABKBLBpB,C-CTCCCDgDhDDaEbE*$ `0Fp*$F `0FpbE~EEEEEFFF'GHHH$H%HsHtHwHxH I IIII*$ `0Fp*$F `0Fp*$ `0Fp$H%HsHtHwHxH I IIIIIJJJJJ5K7K8KKKKKLL LLLLLL%L&L'L1LcL}LLLMMMMMgOhOkOlOmOOOQQQ5Q6Q;Rmo o8o9ooooooooooooo$p%p:p;pnpoppprrrJrKrLrssuuuuuwwxxrysyd|e|}}}}?@no*+_`„Ä ҋӋ܋QRSdffFjGjajbjlGlyl|l>m?mYmZm o oo'o(o7ooooooooooooooooooooooooooppp&p9p;pmo o8o9ooooooo $$x0p 4!*$Z6$ `0Fp*$ `0Fpooooooo$p%p:p;pnp˔||o *$Z6$ h*$ `0Fp $$x0p 4! $$x0p 4! $$x0p 4!*$Z6$ `0Fp npoppprrrJrKrLrssuuuuuwwxxrysy *$Z6$ h*$ `0Fp*$ `0Fp$$x!pp{ppppprr"r#r$r)r-r3r4r7r8rLrWr\r]rqrrrssuuuuuuuuuuuuuuuuuuuwww x xxixjx|x}xyyyy}}@ CJOJQJ5CJOJQJj5CJOJQJU5CJOJQJj CJOJQJU 6OJQJjh CJOJQJU OJQJjOJQJUOJQJ 5OJQJ?LMabjklxyڵ5CJ$OJQJje!5CJOJQJU5CJ$OJQJj5CJ$OJQJU 5OJQJ OJQJjOJQJUOJQJ5CJOJQJj5CJOJQJU5CJOJQJ:y&'?@VWno ,-67MN  ./STU(68PUVۿۿ۱ۿۿۿۿ۱ۿj!5CJOJQJU5CJOJQJ OJQJjOJQJU 5OJQJjUhmHnHOJQJ5CJ$OJQJj5CJ$OJQJU5CJ$OJQJ?M *$d `0Fp,*$ `0Fp,TVW'(78QHIGH*$F `0Fp,*$d `0Fp,*$ `0Fp,VopI[\qr#$12Hs56MN8U +  /0#$4CD./tu5CJOJQJ 6OJQJ5OJQJj5OJQJU 5OJQJOJQJjOJQJU OJQJLHt~,5]^LM*$F `0Fp,*$ `0Fp,befgQT12STpq~9<OPabs12L:;@5OJQJj5OJQJU5CJOJQJ 6OJQJ OJQJjOJQJU 5OJQJOJQJLM45_`r  Mkl67*$ `0Fp,*$F `0Fp,r  Mkl67 Al   &   & 4 5 c    6&?@mqrYtqrde}d Al*$ `0Fp,*$F `0Fp,*$ `0Fp,@BC^_k  %  % 5 b ¸ ¸ ¸ uu5CJOJQJj5CJOJQJU5CJOJQJjUhmHnH5CJ$OJQJj "5CJOJQJU5CJ$OJQJj5CJ$OJQJU5OJQJj5OJQJU 5OJQJ OJQJjOJQJUOJQJ.   &   & 4 5 c    *$F `0Fp,*$ `0Fp,*$d `0Fp,b   5%@lrZsre|$BZ( <   X!!!!h"i""""""""$ $$$$$5CJ$OJQJj5CJ$OJQJU5OJQJj5OJQJU OJQJjOJQJU5CJOJQJ 6OJQJ 5OJQJOJQJB 6&?@mqrYt*$ `0Fp,*$F `0Fp,tqrde}#$CD[)*$ `0Fp,*$F `0Fp,}#$CD[)  = W!X!!!!!g"h""$$L$$$$%%%>%?%X&Y&&8'9'C'D'E''')))M*N*++K,L,p,r,s,t,,,,,,,,, --'-@-S-g-x-------------.!.4.E.V.e.}...d  = W!X!!!!!g"h""$$L$$$$%%%*$d `0Fp,*$F `0Fp,*$ `0Fp,$$%$&$2$3$J$K$U$V$l$m$~$$$%&%'%8%9%=%t%%%%Y&&&&''7'9'C'E'F'\']''))))**/*0*L*L,M,N,V,W,X,˸˚˚˔˪˔˪˪Єj"5CJOJQJU 5OJQJ 6OJQJ5CJOJQJj5CJOJQJU5CJOJQJjUhmHnHOJQJ5CJ$OJQJ5CJ$OJQJj5CJ$OJQJUj^"5CJOJQJU4%>%?%X&Y&&&&8'9'C'D'E''')))M*N*++K,L,p,*$ `0Fp*$ `0Fp,X,],^,n,o,p,q,t,u,,,------11%4&45566*6+6L6M666R:S:;;;;>>W?X???@@CCCCCCCC8G9GGGGGGGGGڻ6CJOJQJj6CJOJQJU jU 5OJQJjOJQJUjUhmHnHOJQJ5CJ$OJQJj5CJ$OJQJU5CJ$OJQJ>p,r,s,t,,,,,,,,, --'-@-S-g-x------*$ `0Fp,*$ `0Fp,*$d `0Fp,--------.!.4.E.V.e.}......//4/F/V/g/*$ `0Fp,*$ `0Fp,....//4/F/V/g/v////////// 0"040D0T0m00000001.1H1\1m111111111222"2:2`2v22222223&333F3W3d3{333333344$4%4'434D4U4q444444444 55"585E5K5T5c555555dg/v////////// 0"040D0T0m00000001.1H1\1m1*$ `0Fp,m111111111222"2:2`2v22222223&333F3*$ `0Fp,*$ `0Fp,F3W3d3{333333344$4%4'434D4U4q44444444*$ `0Fp,*$ `0Fp,44 55"585E5K5T5c555555555556 6666)6*$ `0Fp,*$ `0Fp,5555556 6666)6*6,616=6K6L6N6f6s66666666777F7]7m77777777777788!8,878?8I8R8[8g8o8x88888888888 99&9;9H9]9e9r9999999999:):9:Q:R:T:^:l:w:~::::::::d)6*6,616=6K6L6N6f6s66666666777F7]7m7777*$ `0Fp,*$ `0Fp,77777777788!8,878?8I8R8[8g8o8x88888888*$ `0Fp,8888 99&9;9H9]9e9r9999999999:):9:Q:R:*$ `0Fp,*$ `0Fp,R:T:^:l:w:~::::::::: ;;+;;;D;W;a;|;;;;;*$ `0Fp,*$ `0Fp,:: ;;+;;;D;W;a;|;;;;;;;;;;;;< <<!<1<@<O<g<u<<<<<<<< ==&=0=S=^={========>7>H>R>c>z>>>>>>>>? ?"?2?K?V?W?Y?i????????@@.@:@M@[@w@y@@@@@@@@@@@@A*Ad;;;;;;;;< <<!<1<@<O<g<u<<<<<<<< ==*$ `0Fp,*$ `0Fp,=&=0=S=^={========>7>H>R>c>z>>>>>>>>*$ `0Fp,*$ `0Fp,>? ?"?2?K?V?W?Y?i????????@@.@:@M@[@*$F `0Fp,*$ `0Fp,*$ `0Fp,[@w@y@@@@@@@@@@@@A*A3AJAaAtAAAAAAA*$ `0Fp,*$ `0Fp,*A3AJAaAtAAAAAAAAABB!BOBZBnB|BBBBBBBBCCC+C4CHCTC]CCCCCCCCCCCCC(D1DADUDdDvDDDDDDDDDDD E!E.E:ELEeE|EEEEEEEEEEEEFFFF*F2F;FDFMFUF]FqFFFFFFFFFdAAABB!BOBZBnB|BBBBBBBBCCC+C4CHCTC]CC*$ `0Fp,*$ `0Fp,CCCCCCCCCCCC(D1DADUDdDvDDDDDDDDD*$ `0Fp,*$ `0Fp,DDD E!E.E:ELEeE|EEEEEEEEEEEEFFFF*F2F;F*$ `0Fp,;FDFMFUF]FqFFFFFFFFFFFFFFG GGG7G8G:G*$ `0Fp,*$ `0Fp,FFFFFFG GGG7G8G:GFG^GpGGGGGGGGGGGGGGGGGGGGGGGGGG!H"H$H%H&H`HaHbHHHHHHHHHHsItIIIIIIJJJLJNJPJQJRJJJJJJJ K KK>K?K@K{K|K}KKKKKKK-L.L/LjLkLlLLd:GFG^GpGGGGGGGGGGGGGGGGGGG$Hd*$ !*$ 0d*$ `0Fp,*$ `0Fp,GGGGGGGGGGGGGGGGGGGGGGGHH H!H"H#H$H%H&H'H5H6H7H8H_H`HaHbH}H~HHHHHHHHHHHHHHHHHHHHHHHHHHIIIII9I:I;IK?K@KAKOKPKRKSKzK{K|K}KKKKOJQJ6CJOJQJmHnH6CJOJQJj6CJOJQJUCJ UJJJPJQJRJJJJJJJ K KK>K?K@K{K|K}KKKKKKK*$ ! *$ !dKKKKKKKKKKKKKKKKLL(L)L+L,L-L.L/L0L>L?LALBLiLjLkLlLLLLLLLLLLLLLLLLLLLLL M M M MMMMMM M"M#MJMKMLMMMMMMMMMMMMMMMMMMM6CJOJQJCJ OJQJ6CJOJQJmHnHj6CJOJQJUUK-L.L/LjLkLlLLLLLLLMMMKMLMMMMMMMMMNNNd*$ !LLLLLLMMMKMLMMMMMMMMMMMMM NNNNN"N$NMNNNONNNNNNNNNNNOOOOO'O*OSOTOUOOOOOOOOOOOPP!P"P#P3P6P_P`PaPPPPPPPPPPP0Q3Q5Q6Q7QGQJQsQtQuQQQQQ_MMMMM N NNNNNNN!N"N$N%NLNMNNNONNNNNNNNNNNNNNNNNNNOOOOOOOOOO&O'O*O+OROSOTOUOzO{OOOOOOOOOOOOOOOOO P PPPP P!P"P#P$P2POJQJ6CJOJQJmHnHj6CJOJQJU6CJOJQJCJ UNMNNNONNNNNNNOOOSOTOUOOOOOOO!P"P#P_P`PaPd*$ !2P3P6P7P^P_P`PaPPPPPPPPPPPPPPPPPPP Q!Q/Q0Q3Q4Q5Q6Q7Q8QFQGQJQKQrQsQtQuQ{Q|QQQQQQQQCJ OJQJ6CJOJQJ6CJOJQJmHnHj6CJOJQJU4aPPPPPPP5Q6Q7QsQtQuQQQQQ*$ `0Fp,d*$ !00P/ =!"#$%....()()))()()00P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()0P/ =!"#$%....()()))()()  00P/ =!"#$% P ....()()))()()SDphoenixSDphoenixUDphoenixxSDphoenixSDphoenixSDphoenixSDphoenixUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxSDphoenixSDphoenixSDphoenixUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxUDphoenixxSDphoenixSDphoenixSDphoenixUDphoenixxUDphoenixxUDphoenixxUDphoenixxSDphoenixSDphoenixSDphoenixSDphoenixSDphoenixUDphoenixxUDphoenixxUDphoenixxUDphoenixxSDphoenixSDphoenixSDphoenixSDphoenixSDphoenixSDphoenix% [<@<Normal1$CJOJQJhmH nH <A@<Default Paragraph Font,+@, Endnote Text6*@6Endnote ReferenceH*.@. Footnote Text8&@!8Footnote ReferenceH*O1Heading"OA" Right Par&OQ& Bibliogrphy$Oa$ SubheadingN@NTOC 1&$*$d ! @OJQJJ@JTOC 2"$*$d ! @OJQJJ@JTOC 3"$*$ 0d ! @OJQJJ@JTOC 4"$*$ 0d ! @OJQJJ@JTOC 5"$*$x0d ! @OJQJ2@2TOC 6*$0 $*@*TOC 7 *$02@2TOC 8*$0 $2@2TOC 9*$0 $ F @FIndex 1 $*$d @OJQJF @FIndex 2!$*$-d @OJQJ6.@6 TOA Heading "*$ $""@"Caption#2OA2_Equation Caption %BUoB juB!,FOY٘a t(MTUVWXYZ"[&\*].^2_6`:a>bBcFdJeNfRgVhZi^j 33333o     Fvvvvv(YYYYYHHHHH)))))fSL     JF( ( ( ( ( f G  *0:FQr^s`wzA}$nG3N<_}2 I^f ow päGe<JXgr%+/5JCRZfpp@ٜyV@b $$X,GsIKM2PQ #%(+/68:=AEILOQUW]_bdhjnstwy}; / '()g017?yEGKRYdsv(x&yz {{p}~wuA B )/)2jDT^f~msn~ @<S[¹. F=J5G2+"'+,07?<bEILSxZtfonpsyCHM t%p,-g/m1F34)678R:;=>[@ACD;F:G$HJKNaPQ     "$&'),-.0124579;<?@BCFGHJMNPRSVXYZ\^`aefgikmopquvxz|~Z&8=%w5}.( 4C/oJ+JW7,$H]Sr}.5:*AFLQ!*3>DKT[clr{(9t((CM   .04CE bqswDSVZil3BEIX[#&*9<&)r  "t  y  ! % ) 8 <   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!8@ ` (  Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z   s *{? Z   s *{? Z   s *{?  Z   s *{?  Z   s *{?  Z  s *{?  Z  s *{?  Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z  s *{? Z  s *{? B S  ?H&3C Vo!-5G}HOZ"T p(M!+p@!+p@!+p@!+p@!+p@!+p@!+p@ !+p@ !+p@ !+p@ !+p@ !+p@!+p@!+p@!+p@!+p@!+p@!+p@!+p@!+p@!+p@!+p@!+p@!+p@ >Fhp;BZc#+S[^f goT \ ow  0;NU_g ')1_g 19^f#0 + 3 ["c"""""""""""$$%%@(H(**T+\+,,u.}.'0/044 7(777:::: ;;<<>>??6C>CDDiEqEFFGGHHhIpIJJKLLLLLOO6P9PPPPPPPPPPPPPQQSSUU(X0X}YYMZUZZZZZ\\Z]b]]]__ ````ddffff&g.ghh.i5iFiOiiiiiiillmm n nqoyooooopp+q3qtqqqqqqrrac4<GPw. 5 Y ` z ~     c k G K   4 ; 03S[9<}),PSnu;CY[ moGIjl  ""$$%%'%>%@%4&8&&&f'h'''I(K())R+Z+ ,,6-;---5.<..... ////00001182@2,3/3334477U9X92:5:H:K:;;#;+;l<n<<=>>??W@Y@DDEE%E0EEEFF5G7GvGxGHHHHHHjIlIeJgJ3K5KLLxMMRNZNOOPPQQQQ R RVVX X\\4^<^^^^^3_5_``P`R`````\a^aaaÂz|w…ʅʼn5=֎ڎ>Fhks|#&ԕە GOHP˘Ҙ ?FGINP֜ݜIPԝםILegiqY`mt ) =F¥˥%-6JS LNaiz29аְ7@y˱Ա/8 FO|QZ",=D,3luGP{ )EGac',BK\enpmo)/5="'ST%W_*63;"$=?6> 6G]es{  ' /    s{pxY`*1kr,3    !!!!!!6">"A"I"l"q""""""".#6#o#w#?$G$r$z$$$$$$$B%J%%%%%%&&&&&&&''''( (](_((((((( ))W)_)))))))U*]*u*}*+ +V+X+++V,X,n,v,#.%.0.8.F.H.X.`.......//B0I05577a8i88888p:x:>>A>I>EE GG8G@GGGHHII3J;JJJLLLL(M/M[NcN;PCPSSX X!X,X5X@XY Y(Y,YYYZZcZgZ8]<]]]^^V_Z___5b?b?kGkxk|kkkkkkkHlKlllll&n-nnnooopq+q7q?qqqqq ssgsjsuuvvxxyyyyw{ aeˇχ|FJZ^gk DS{%-w{Ťդߤ&YaߪѬ٬IJ AEHP15 koLT/79= GKemKSai;C  MVvx2479<>"*YaDFag Ya      % - i q     !ORUX[^giFNz}24RTLUtxL T       !!<"D"""###&#-###$$$$''))**#*'*6*9*[*_***++++,,z,,;-C-----...!.00222#2223333334 444#4'4.424A4D4]4^4q4s4z4|44444444444445555=5?5g5i5t5v5555555555566777777888899;;;;*=2=a=i=v=z=================> >>>!>)>v@~@@@@@@@@@@@.A5AeAnAAA4B6B=B?BFBHBBBBBBBBB_CgCCCCCCCCCCCCCCCCCCD#D&D8D}DDDDDDDE^EqEtEEEEEE _PID_GUIDAN{6A556121-92BE-11D3-B365-00A0CC21B8C5}  !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~      !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~      !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~Root Entry Fc&Data #1Table\WordDocumentmkSummaryInformation(DocumentSummaryInformation8CompObjjObjectPoolc&c&  FMicrosoft Word Document MSWordDocWord.Document.89q