home *** CD-ROM | disk | FTP | other *** search
/ The Education Master 1994 (4th Edition) / EDUCATIONS_MASTER_4TH_EDITION.bin / files / progng_c / pcopt / manual.doc < prev    next >
Encoding:
Text File  |  1993-10-28  |  72.4 KB  |  1,623 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                                  PC_Opt
  11.                                version 1.1
  12.  
  13.  
  14.  
  15.                               User's Guide 
  16.  
  17.  
  18.  
  19.  
  20.                   Copyright (c) 1993 Optimite Systems.
  21.                           All Rights Reserved.
  22.  
  23. DEFINITION OF SHAREWARE
  24.  
  25. Shareware distribution gives users a chance to try software before buying
  26. it. If you try a Shareware program and continue using it, you are expected
  27. to register. Individual programs differ on details -- some request
  28. registration while others require it, some specify a maximum trial period.
  29. Copyright laws apply to both Shareware and commercial software, and the
  30. copyright holder retains all rights, with a few specific exceptions as stated
  31. below. Shareware authors are accomplished programmers, just like
  32. commercial authors, and the programs are of comparable quality. (In both
  33. cases, there are good programs and bad ones!) The main difference is in
  34. the method of distribution. The author specifically grants the right to copy
  35. and distribute the software, either to all and sundry or to a specific group.
  36. For example, some authors require written permission before a
  37. commercial disk vendor may copy their Shareware.  Shareware is a
  38. distribution method, not a type of software. You should find software that
  39. suits your needs and pocketbook, whether it's commercial or Shareware.
  40. The Shareware system makes fitting your needs easier, because you can
  41. try before you buy. And because the overhead is low, prices are low also.
  42. Shareware has the ultimate money-back guarantee -- if you don't use the
  43. product, you don't pay for it.  
  44.  
  45. DISCLAIMER - AGREEMENT  
  46.  
  47. Users of PC_Opt must accept this disclaimer of warranty: "PC_Opt is
  48. supplied as is. The author disclaims all warranties, expressed or implied,
  49. including, without limitation, the warranties of merchantability and of
  50. fitness for any purpose. The author assumes no liability for damages,
  51. direct or consequential, which may result from the use of PC_Opt."
  52. PC_Opt is a "shareware program" and is provided at no charge to the user
  53. for evaluation. Feel free to share it with your friends, but please do not
  54. give it away altered or as part of another system. The essence of
  55. "shareware" software is to provide personal computer users with quality
  56. software without high prices, and yet to provide incentive for
  57. programmers to continue to develop new products. If you find this
  58. program useful and find that you are using PC_Opt and continue to use
  59. PC_Opt after a reasonable trial period, you must make a registration
  60. payment of $15.00 to Optimite Systems. The $15.00 registration fee will
  61. license one copy for use on any one computer at any one time. You must
  62. treat this software just like a book. An example is that this software may
  63. be used by any number of people and may be freely moved from one
  64. computer location to another, so long as there is no possibility of it being
  65. used at one location while it's being used at another. Just as a book cannot
  66. be read by two different persons at the same time. Commercial users of
  67. PC_Opt must register and pay for their copies of PC_Opt within 30 days
  68. of first use or their license is withdrawn. Site-License arrangements may
  69. be made by contacting Optimite Systems. Anyone distributing PC_Opt for
  70. any kind of remuneration must first contact Optimite Systems at the
  71. address below for authorization. This authorization will be automatically
  72. granted to distributors recognized by the (ASP) as adhering to its
  73. guidelines for shareware distributors, and such distributors may begin
  74. offering PC_Opt immediately (However Optimite Systems must still be
  75. advised so that the distributor can be kept up-to-date with the latest
  76. version of PC_Opt). You are encouraged to pass a copy of PC_Opt along
  77. to your friends for evaluation. Please encourage them to register their
  78. copy if they find that they can use it. All registered users will receive a
  79. printed manual, information on product enhancements, ninety days of free
  80. support, and a copy of the latest version of the PC_Opt.
  81.  
  82. Support for Registered Users
  83.  
  84. Users will receive ninety days free support upon registering PC_Opt. This
  85. support will be by mail and compuserve email. Additional phone support
  86. will be supplied if all other means of support do not resolve the problem.
  87. We are limited in the amount of phone support we can provide because of
  88. the low registration fee.
  89.  
  90. This program is produced by a member of the Association of Shareware
  91. Professionals (ASP). ASP wants to make sure that the shareware principle
  92. works for you. If you are unable to resolve a shareware-related problem
  93. with an ASP member by contacting the member directly, ASP may be
  94. able to help. The ASP Ombudsman can help you resolve a dispute or
  95. problem with an ASP member, but does not provide technical support for
  96. members' products. Please write to the ASP Ombudsman at 545 Grover
  97. Road, Muskegon, MI 49442 or send a CompuServe message via
  98. CompuServe Mail to ASP Ombudsman 70007,3536."
  99.  
  100.  
  101.  
  102. How To Register
  103.  
  104. Simply print and fill out the form in listed in the file order.doc 
  105. and send along with a check or money order for $15.00 (+ 5.00 shipping & 
  106. handling) to:
  107.  
  108. Optimite Systems
  109. 1000 Singleton Blvd.
  110. Dallas, Texas 75212
  111.  
  112. In registering this software, you are helping us in our efforts to continue
  113. to improve and extend optimization technology to new platforms. As
  114. mentioned previously, all registered users will receive a printed manual,
  115. information on product enhancements, ninety days of free support, and a
  116. copy of the latest version of the PC_Opt. 
  117.  
  118.  
  119. Trademarks
  120.  
  121. PC_Opt is a trademark of Optimite Systems
  122.  
  123. Borland C++ is a trademark of Borland International, Inc.
  124.  
  125. OS/2 is a trademark of IBM corporation
  126.  
  127. INTEL is a trademark of Intel, Inc.
  128.  
  129. Microsoft C and MS-DOS are trademarks of Microsoft Corporation
  130.  
  131. Windows is a registered trademark of Microsoft Corporation. TABLE OF CONTENTS
  132.  
  133. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
  134.  
  135. REQUIREMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
  136.  
  137. GENERAL CAPABILITIES . . . . . . . . . . . . . . . . . . . . . . . .  2
  138.  
  139. DISTRIBUTION DISKETTE CONTENTS . . . . . . . . . . . . . . . . . . .  2
  140.  
  141. STEP BY STEP OPERATION . . . . . . . . . . . . . . . . . . . . . . .  2
  142.  
  143. CHAPTER 1   COMMAND LINE OPTIONS . . . . . . . . . . . . . . . . . .  4
  144.               /rxxxx . . . . . . . . . . . . . . . . . . . . . . . .  4
  145.               /oxxxx . . . . . . . . . . . . . . . . . . . . . . . .  5
  146.               /sxxxx . . . . . . . . . . . . . . . . . . . . . . . .  5
  147.               /lxxxx . . . . . . . . . . . . . . . . . . . . . . . .  5
  148.               /mxxxx . . . . . . . . . . . . . . . . . . . . . . . .  6
  149.               /exxxx . . . . . . . . . . . . . . . . . . . . . . . .  6
  150.               /d99999. . . . . . . . . . . . . . . . . . . . . . . .  6
  151.               /b . . . . . . . . . . . . . . . . . . . . . . . . . .  6
  152.               /c . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  153.               /g . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  154.               /n . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  155.               /t . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  156.               /z . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  157.  
  158. CHAPTER 2   SPECIFYING INPUT OBJECT MODULES. . . . . . . . . . . . .  8
  159.               Command Line Input . . . . . . . . . . . . . . . . . .  8
  160.               Linker Response File Input . . . . . . . . . . . . . .  8
  161.               Makefile Input . . . . . . . . . . . . . . . . . . . .  9
  162.  
  163. CHAPTER 3   CREATING DECLARATION FILES . . . . . . . . . . . . . . . 11
  164.               Non Parseable Object Module Information. . . . . . . . 11
  165.               Comments in Declaration Files. . . . . . . . . . . . . 12
  166.  
  167. CHAPTER 4   PARSEABLE OBJECT MODULES . . . . . . . . . . . . . . . . 13
  168.  
  169. CHAPTER 5   PC_Opt OPTIMIZATIONS . . . . . . . . . . . . . . . . . . 20
  170.               Far to Near Calling Conversion . . . . . . . . . . . . 20
  171.               Register Passing Conversion. . . . . . . . . . . . . . 20
  172.               Unreachable Procedure Deletion . . . . . . . . . . . . 20
  173.               Stack Clearing Conversion. . . . . . . . . . . . . . . 20
  174.               NOP Instruction Deletion . . . . . . . . . . . . . . . 21
  175.  
  176. CHAPTER 6   THIRD PARTY OBJECT LIBRARIES . . . . . . . . . . . . . . 22
  177.  
  178. CHAPTER 7   PROGRAM TESTING. . . . . . . . . . . . . . . . . . . . . 23
  179.  
  180. CHAPTER 8   SAMPLE RUN . . . . . . . . . . . . . . . . . . . . . . . 24
  181.  
  182. APPENDIX A  ERROR MESSAGES . . . . . . . . . . . . . . . . . . . . . 26
  183.  
  184. APPENDIX B  COMMON QUESTIONS . . . . . . . . . . . . . . . . . . . . 38
  185.  
  186. INDEX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
  187. INTRODUCTION
  188.  
  189. PC_Opt (Post Compile Optimizer) performs optimizations across all object
  190. modules before program linking is performed. These optimizations are
  191. based upon analysis of the complete program structure rather than a single
  192. module. 
  193.  
  194. PC_Opt analyzes program control flow hierarchy and consolidates code
  195. into segments where possible. Conversion of far call and return
  196. instructions to near call and return instructions is then performed.
  197. Conversion to register parameter passing is performed where possible.
  198. Also stack clearing conversion and non invoked code elimination is
  199. performed. 
  200.  
  201. All analysis and subsequent editing of code is performed on an object
  202. module level. The output from this process is also in the form of object
  203. module files. Additionally, a linker response file is generated which
  204. consists of a list of these output object files. The output object files can
  205. be linked by the programmer's usual linker in order to produce an
  206. executable file.
  207.  
  208. This post compile form of optimization is possible only if the input object
  209. modules comply to a certain format or are specified otherwise as being
  210. non compliant. This manual describes this  specification process to the
  211. extent that PC_Opt can be utilized with a minimum of effort.
  212.  
  213.  
  214. REQUIREMENTS
  215.  
  216. PC_Opt runs under MS-DOS versions 3.0 and later. A minimum 512k of
  217. RAM memory is required. Additional memory is preferred when dealing
  218. with large size programs.
  219.  
  220. This manual utilizes assembly language examples in order to describe
  221. PC_Opt functionality. The reader is assumed to possess a basic
  222. understanding of 80X86 assembly language concepts.
  223.  
  224. GENERAL CAPABILITIES
  225.  
  226. PC_Opt will read in and edit object files originating from C language
  227. source files and generated by Borland C++ 3.1 (C++ extensions not yet
  228. supported). It will also optimize any OMF standard object module that
  229. complies with the guidelines set forth in this manual to ensure correct
  230. object module interpretation (see chapter 4, PARSEABLE OBJECT
  231. FILES). Declaration files containing non parseable object module lists are
  232. also input to the program and utilized in optimization analysis (see chapter
  233. 3, CREATING DECLARATION FILES). 
  234.  
  235. Runtime declaration files are included on the distribution diskette. These
  236. files contain non parseable lists for each of the Borland runtime libraries
  237. (see DISTRIBUTION DISKETTE CONTENTS). 
  238.  
  239. PC_Opt operates on DOS applications only. Windows, OS/2 and 32 bit
  240. applications are currently not supported.
  241.  
  242. DISTRIBUTION DISKETTE CONTENTS
  243.  
  244. The distribution diskette contains the following files:
  245.  
  246.        BM.dat               Borland Medium Model runtime declaration
  247.                             file
  248.        BL.dat               Borland Large Model runtime declaration
  249.                             file
  250.        BH.dat               Borland Huge Model runtime declaration file
  251.  
  252.        opt.exe              PC_Opt executable
  253.        read.me              Additions to user manual and reference
  254.                             guide
  255.        
  256.  
  257.   STEP BY STEP OPERATION
  258.  
  259. The following is a brief description of the steps necessary to run PC_Opt
  260. on a large code model application. An sample run detailing these steps can
  261. be found in chapter 9, SAMPLE RUN.
  262.  
  263. 1.     Compile all code to be linked into the application.
  264.  
  265. 2.     Select the correct runtime declaration file for the language model
  266.        used.
  267.  
  268. 3.     Create an application declaration file corresponding to the
  269.        application object code. This step is not required if the /g
  270.        command line option is specified.
  271.  
  272. 4.     Run PC_Opt with the results generated from steps 1, 2, and 3
  273.        serving as input.
  274.  
  275. 5.     Link the object files created in step 4 in order to create the final
  276.        executable file. CHAPTER 1   COMMAND LINE OPTIONS
  277.  
  278. PC_Opt's command line has the following syntax:
  279.  
  280. opt [/options] [object files], [library files]
  281.  
  282. where:
  283.  
  284. opt - invokes PC_Opt.
  285.  
  286. options - the following are descriptions of the command line options
  287. available for PC_Opt:
  288.  
  289. /axxxx        Application declaration filename. Specifies the application
  290.               declaration file to be read by PC_Opt. This file contains a
  291.               list of non parseable object modules and libraries
  292.               corresponding to the application object code. This option
  293.               defaults to the filename OPT.DAT. This file is not required
  294.               if the /g command line option is present.
  295.  
  296.               Example:
  297.  
  298.               opt /c /amcd.dat obj1 obj2 obj3
  299.               
  300.               This example will read from the application declaration file
  301.               mcd.dat.
  302.  
  303. /rxxxx        Runtime declaration filename. Specifies the runtime
  304.               declaration file. This file contains a list of non parseable
  305.               object modules and libraries corresponding to the
  306.               compiler's runtime object libraries for a particular language
  307.               model. This option defaults to the filename ROPT.DAT
  308.  
  309.               Example:
  310.  
  311.               opt /rbl.dat /c obj1 obj2 obj3, lib1
  312.  
  313.               This example uses the Borland large memory model
  314.               runtime declaration file as input. This file is supplied on
  315.               the distribution diskette (see DISTRIBUTION DISKETTE
  316.               CONTENTS). 
  317.  
  318.               Note that the /a option is absent from this command line.
  319.               This means that the application declaration filename will
  320.               default to OPT.DAT. 
  321.  
  322. /oxxxx        Output object file root name. Specifies the first letters of
  323.               the output object files. Output object file names are
  324.               constructed from up to four alphanumeric characters
  325.               followed by a numbered sequence. If this option is not
  326.               specified then the output object file name defaults to OPT.
  327.  
  328.               Example: 
  329.  
  330.               opt  /c  /oarc  obj1 obj2 ... objn
  331.  
  332.               The above command line argument will produce the
  333.               following n output files:
  334.  
  335.               arc1.obj arc2.obj ... arcn.obj
  336.  
  337. /sxxxx        segment root name. Specifies the first characters of the
  338.               names of the code segment(s) that are created by PC_Opt.
  339.               New segment names are constructed from up to five
  340.               alphanumeric characters followed by a numbered sequence.
  341.               This option defaults to OPT.
  342.  
  343.               Example:
  344.  
  345.               opt /sNEWSEG /c obj1 obj2 obj3 obj4 obj5
  346.  
  347.               This example will assign n newly created segments in the
  348.               output object files the names NEWSE1, NEWSE2, ..,
  349.               NEWSEn. Note that the 'G' is truncated due to the five
  350.               character limit.
  351.  
  352. /lxxxx        Output linker response file. Specifies the name of the linker
  353.               response file to be generated by PC_Opt. This file contains
  354.               a list of all output object file names and can be used as a
  355.               response file for the subsequent link. If this option is not
  356.               specified then the default output linker response file name
  357.               OPT.LRF is assigned.
  358.  
  359.               Example: 
  360.  
  361.               opt /c obj1 obj2 ... objn
  362.  
  363.               The above command line argument does not specify an
  364.               output link response file so the default output linker
  365.               response file OPT.LRF is created which contains a list of
  366.               the following n output files:
  367.  
  368.               opt1.obj opt2.obj ... optn.obj
  369.  
  370.               This file can be used as an input link response file for the
  371.               subsequent link.
  372.  
  373. /mxxxx        Makefile name. Specifies the name of the makefile that is
  374.               to be searched in order to locate the link command line that
  375.               contains the input object files and libraries. If the /e option
  376.               is present and no makefile name is specified then this
  377.               option defaults to the makefile name makefile.mak 
  378.  
  379. /exxxx        Executable filename. Specifies the name of the executable
  380.               filename that is to be searched for in the input makefile in
  381.               order to retrieve the input object files and object libraries.
  382.               The executable filename is expected to precede a make
  383.               dependency list (see Makefile Input).
  384.  
  385.               Example:
  386.  
  387.               opt /c /mconstruc.mak /edsort.exe
  388.  
  389.               This example specifies that the input object files and object
  390.               libraries are to be found on the link command line
  391.               following the dsort.exe make dependency list in the make
  392.               file named construc.mak. 
  393.  
  394. /d99999       Maximum consolidated segment size. Sets the maximum
  395.               size for consolidated segments. This defaults to 65535 the
  396.               maximum addressable segment size. 
  397.  
  398. /b            Disable stack clearing conversion. This option turns off the
  399.               conversion of stack clearing instructions from the C
  400.               language to Pascal convention (see Stack Clearing
  401.               Conversion).
  402.  
  403. /c            Case sensitive public symbols. This option tells PC_Opt to
  404.               treat all public symbol names as case sensitive. This option
  405.               is required when dealing with C language object files
  406.               because all symbols in the C language are defined to be
  407.               case sensitive.
  408.  
  409. /g            Edit supported compiler code only. This option allows
  410.               PC_Opt to be run without creating application declaration
  411.               files. Only object modules that were generated by a
  412.               supported compiler (Borland) are considered parseable
  413.               when this option is specified. PC_Opt will consider any
  414.               non supported compiler generated code to be non parseable
  415.               instead of reading in a non parseable list.
  416.  
  417. /n            No default library search. This option tells PC_Opt to
  418.               ignore the default object libraries specified in object
  419.               modules. 
  420.  
  421. /t            Generate edited code size report. This option will generate
  422.               a report containing the input and output code segment sizes
  423.               of all parseable object modules.
  424.  
  425. /z            Allow zero opcode instruction. This option allows the
  426.               existence of the add [bx+si],al machine instruction. This
  427.               instruction is composed of two bytes containing values of
  428.               zero. Detection of this instruction usually indicates
  429.               immediate data within a code segment. By default, PC_Opt
  430.               does not allow this instruction in parseable object modules. 
  431.               A fatal error occurs upon discovery of its existence. If this
  432.               option is enabled then a warning message is displayed
  433.               instead of a fatal error message.
  434. CHAPTER 2   SPECIFYING INPUT OBJECT MODULES
  435.  
  436. PC_Opt retrieves object files and object library files as input. There are
  437. three methods for specifying these files:
  438.  
  439. By entering object files and libraries directly on the command line
  440.  
  441. By including a link response file on the command line
  442.  
  443. By specifying a link command line within a makefile
  444.  
  445. Command Line Input
  446.  
  447. The list of object files and object libraries may be entered directly on the
  448. command line (after all options are entered). A comma must separate the
  449. last object file and the first object library file.
  450.  
  451.               Example:
  452.  
  453.               opt  /c obj1 obj2 obj3, lib1 lib2
  454.  
  455. This example specifies that three object files along with two object library
  456. files are to serve as input to PC_Opt.
  457.  
  458. Linker Response File Input
  459.  
  460. A linker response file that contains the list of input object files and object
  461. libraries may be included on the command line. A response file is denoted
  462. on the command line by preceding the filename with the '@' character.
  463. This response file must follow all options on the command line. The
  464. syntax of the contents of this response file is similar to that of the input
  465. to Microsoft's or Borland's linker:
  466.  
  467.               objfiles, [exefile], [mapfile], [libfiles]
  468.  
  469. PC_Opt accepts this syntax format so that a single response file may be
  470. used as both input to the user's linker and to PC_Opt itself. NOTE: This
  471. syntax differs from the normal syntax of command line input (see above)
  472. in that additional commas are necessary to delineate the exefile and
  473. mapfile.
  474.  
  475.               Example:
  476.  
  477.               opt /c obj1 obj2 obj3 obj4, lib1 lib2 lib3
  478.  
  479. This command line input example can be similarly entered as input from
  480. a linker response file:
  481.  
  482.               opt /c @linkinp.lrf
  483.  
  484. Where the contents of the file LINKINP.LRF are:
  485.  
  486.               obj1 obj2 obj3 obj4,,, lib1 lib2 lib3 
  487.  
  488. Note the additional two commas inserted to delineate the exefile and
  489. mapfile.
  490.  
  491. Makefile Input
  492.  
  493. A makefile and executable filename may be specified on the command line
  494. so that input object files and object libraries may be extracted off of a link
  495. command line in an existing makefile. The executable filename must
  496. appear explicitly in the makefile (implicit make dependency lines are
  497. currently not supported). Also, macro definitions and makefile directives
  498. are ignored by PC_Opt. The following algorithm describes exactly how
  499. the input object file list is located in a makefile:
  500.  
  501.        The makefile is searched from top to bottom for the first
  502.        occurrence of the specified executable filename found starting in
  503.        column one. This filename must be followed by a colon according
  504.        to make syntax rules. All items that follow this colon are
  505.        considered to be elements in a make dependency list. All filenames
  506.        in the make dependency list are parsed and the end of list is
  507.        located. This dependency list may carry over across multiple lines
  508.        by the existence of a backslash continuation character '\' at the end
  509.        of a line. The next non blank line is then located. This line is
  510.        interpreted as the link command line for the executable filename.
  511.        This line should be indented according to make syntax rules so a
  512.        blank or tab character is checked for in column one. The link
  513.        command and all link parameter flags are parsed over. The next
  514.        item encountered on the line is considered to be the start of the
  515.        input object file list. A link response file may appear at any point
  516.        after the link command on this line. A response file is denoted by
  517.        preceding the filename with the '@' character.
  518.  
  519.               Example:
  520.  
  521.               opt /c /mstart.mak /estart.exe
  522.  
  523. The above example specifies that the filename start.exe is to be searched
  524. for in the makefile start.mak.
  525.  
  526. Contents of start.make:
  527.  
  528.               start.exe : startup.obj  diff.obj edit.obj comp.obj
  529.                 link @link.lrf
  530.  
  531.               startup.obj: startup.asm startup.inc
  532.                 tasm  startup.asm
  533.  
  534.               diff.obj: diff.c comp.h
  535.                 bcc -ml -C -c diff.c
  536.  
  537.               edit.obj: edit.c edit.h
  538.                 bcc -ml -C -c edit.c
  539.  
  540.               comp.obj: comp.c
  541.                 bcc -ml -C -c comp.c
  542.  
  543. start.exe is found in the first column of line one followed by a colon and
  544. dependency list. The end of the dependency list is located and an indented
  545. link command line follows. After parsing over the link command the
  546. response file LINK.LRF is found and opened for further parsing.
  547.  
  548. The contents of LINK.LRF:
  549.  
  550.               /m /l startup diff edit comp, start, start, +
  551.                 lib1 lib2 lib3 lib4
  552.  
  553. The link parameters /m /l are parsed over and startup, diff, edit and comp
  554. are loaded as input object files. the executable filename (start.exe) and
  555. map filename (start.map) specifications are skipped over and lib1, lib2
  556. ,lib3 and lib4 are loaded as input object library files. Note the link
  557. response file continuation character '+' is different than the backslash
  558. continuation character '\' used in makefiles and may vary for different
  559. linkers. CHAPTER 3   CREATING DECLARATION FILES
  560.  
  561. Declaration files serve as input to PC_Opt and contain a list of non
  562. parseable object module and library information used by PC_Opt during
  563. the optimization analysis phase. It is important that this non parseable
  564. information be correct in order to preserve output program integrity. 
  565.  
  566. Declaration files for the specific compiler language model runtime
  567. libraries are provided on the distribution diskette. The runtime declaration
  568. file is specified with the /r command line option (see chapter 1,
  569. COMMAND LINE OPTIONS). 
  570.  
  571. An application declaration file must be created if the /g command line
  572. parameter is not issued. This file contains the list of non parseable object
  573. modules and libraries which corresponds to the application object code.
  574. This declaration file must be maintained as modifications to the application
  575. occur. The application declaration filename is specified with the /a
  576. command line option (see chapter 1, COMMAND LINE OPTIONS). 
  577.               
  578. Non Parseable Object Module Information
  579.  
  580. Object modules must comply to certain rules in order to be correctly
  581. interpreted and edited by PC_Opt. If an object module does not adhere to
  582. these rules it is considered to be non parseable. No instruction parsing or
  583. editing is performed on non parseable object modules. 
  584.  
  585. Object modules that are generated by supported compilers are considered
  586. to be compliant with parseable guidelines. Non supported compiler and
  587. assembler generated object modules must be inspected in order to
  588. determine if they are compliant and therefore considered parseable. These
  589. guidelines for determining whether or not an object module is parseable
  590. are described in chapter 4, PARSEABLE OBJECT MODULES.
  591.  
  592. Non Parseable Object Module Libraries
  593.  
  594. If an object module library is included in a non parseable list then all
  595. object modules within that library that have not been generated by a
  596. supported compiler will be considered non parseable. Object modules
  597. within a library may also be listed separately in a non parseable list.
  598.  
  599. The format for non parseable object module or library listings in a
  600. declaration file is as follows:
  601. Each file must be on a separate line and include an obj or lib file
  602. extension so that PC_Opt can determine if an object module or library is
  603. being listed.
  604.  
  605. The following is the contents of an application declaration file where 4
  606. object modules and one object module library are declared as non
  607. parseable.
  608.  
  609.        Example:
  610.  
  611.        MEM.OBJ
  612.        DISKIO.OBJ
  613.        QSORT.OBJ
  614.        LINE32.OBJ
  615.        GRAFIT.LIB
  616.  
  617. Comments in Declaration Files
  618.  
  619. Comment lines are permitted in declaration files as long as they are
  620. preceded by a semicolon ';' character. Comments can be used to explain
  621. why a particular object module is considered to be non parseable.
  622. CHAPTER 4   PARSEABLE OBJECT MODULES
  623.  
  624. As stated previously, object modules must comply with certain rules in
  625. order to be correctly interpreted and edited by PC_Opt. If an object
  626. module does not adhere to these rules it is considered to be non parseable
  627. and will require a non parseable declaration. Object modules that are
  628. generated by supported compilers are parseable due to the standard format
  629. of supported compiler generated object code. The non parseable
  630. restrictions detailed here are generally related to more obscure coding
  631. practices that would not be found in compiler output code.
  632.  
  633. The following is a listing of properties that are required of an object
  634. module in order for it to be considered parseable:
  635.  
  636. - standard stack frame parameter accessing
  637.  
  638. The standard stack frame parameter accessing method must be used in
  639. order to retrieve procedure input parameters off of the stack. This method
  640. of stack based parameter accessing is employed in all compiler generated
  641. object code. Register parameter passing conventions are not affected by
  642. this restriction. The standard stack frame parameter accessing method is
  643. described as follows:
  644.  
  645. The bp register is set to the value of the stack pointer register sp and stack
  646. based input parameters are accessed in a [bp + positive displacement]
  647. indexed addressing mode. 
  648.  
  649.                      Example:
  650.  
  651.                      _abc   proc    far
  652.                             push    bp
  653.                             mov     bp,sp
  654.                             ___
  655.                             ___
  656.                             mov     al,byte ptr [bp+6] ; get input byte
  657.                             ___
  658.                             ___
  659.                             pop     bp
  660.                             retf
  661.                      _abc   endp
  662.  
  663. In procedure _abc the stack frame is set by first saving the contents of the
  664. bp register with the push bp instruction and then assigning the value of
  665. sp to bp with the mov bp,sp instruction. The input byte parameter is then
  666. accessed off of the stack with the mov al,byte ptr [bp+6] instruction.
  667. Finally, the contents of the bp register are restored with the push bp
  668. instruction. This example illustrates standard stack frame accessing. 
  669.  
  670.                      Example:
  671.  
  672.                      _xyz   proc    far
  673.                             cmp     byte ptr _value,0
  674.                             jnz     noinc
  675.                             cmp     ax,0
  676.                             jnz     noinc
  677.                             inc     byte ptr _value
  678.                      noinc:
  679.                             retf
  680.                      _xyz   endp
  681.  
  682. In procedure _xyz there is no stack based parameter accessing performed
  683. so no standard stack frame setup instructions are required. This procedure
  684. is would not require a non parseable declaration for the object module in
  685. which it resides because there is no non standard stack based parameter
  686. accessing present.
  687.               
  688.                      Example:
  689.  
  690.                      _zyx   proc    near
  691.                             pop     cx
  692.                             pop     ax
  693.                             cmp     ax,0
  694.                             jnz     noinc
  695.                             inc     ax
  696.                      noinc:
  697.                             push    cx
  698.                             push    cx
  699.                             ret
  700.                      _zyx   endp
  701.               
  702. Procedure _zyx accepts an input stack based word parameter and returns
  703. the word value or 1 if the word value is zero. The pop cx instruction
  704. increments the stack pointer so that it points to the input word on the
  705. stack. In doing this the procedure return address is stored in the cx
  706. register. The pop ax instruction retrieves the input word off of the stack
  707. into the ax register. The last two push cx instructions set the stack pointer
  708. back to its original value and also store the procedure return address from
  709. cx back into its proper location on the stack. This procedure illustrates a
  710. non standard stack frame method of accessing parameters off of the stack.
  711. This procedure would require that a non parseable object module
  712. declaration be created for the object module in which it resides.
  713.  
  714. As a corollary, any indexed addressing instructions which utilize the bp
  715. register and a positive displacement must be used only in accessing the
  716. parameters off of the stack. No use of the bp register to access items in
  717. the data segment (in the case where ss equals ds) is permitted in parseable
  718. object modules.
  719.  
  720. - no non relocatable immediate data in code segments
  721.  
  722. PC_Opt attempts to detect non relocatable immediate data inside parseable
  723. code segments and issues a fatal error upon finding any. It is possible,
  724. however, for an occurrence of non relocatable immediate data to go
  725. undetected. This would result in an incorrect machine code interpretation.
  726. PC_Opt requires all object modules that contain code segment non
  727. relocatable immediate data to be declared as non parseable. This
  728. requirement eliminates the possibility of incorrect machine code
  729. interpretation. 
  730.  
  731. The exception to this requirement involves immediate comparison data
  732. within code generated by a C language switch statement. PC_Opt is able
  733. to recognize switch statement immediate data in supported compiler object
  734. code. This allows all supported compiler generated code to remain
  735. parseable.
  736.  
  737. Supported compiler generated object code will not include any non
  738. relocatable immediate data within code segments.
  739.  
  740.                      Example:
  741.  
  742.                      _msg   proc    far
  743.                             push    bp
  744.                             mov     bp,sp
  745.                             jmp     overmsg
  746.                      msgaddr:
  747.                             db      'dept of redundancy dept'
  748.                      overmsg:
  749.                             push    cs
  750.                             push    offset msgaddr
  751.                             call    far ptr _displaymsg
  752.                             pop     cx
  753.                             pop     cx
  754.                             pop     bp
  755.                             retf
  756.                      _msg   endp
  757.               
  758. Procedure _msg contains non relocatable immediate data at the location
  759. msgaddr and therefore the object module that contains this procedure
  760. should be declared as non parseable.
  761.  
  762.                      Example:
  763.  
  764.                      _msg2          proc   far
  765.                             push    bp
  766.                             mov     bp,sp
  767.                             jmp     overaddr
  768.                      addr:
  769.                             dw      offset _msg2
  770.                      overaddr:
  771.  
  772.                             ---
  773.                             ---
  774.                             pop     bp
  775.                             retf
  776.                      _msg2          endp
  777.  
  778. Procedure _msg2 contains relocatable immediate data at the location addr.
  779. This data is considered to be relocatable because the value of offset
  780. _msg2 is relative to the address of the relocatable segment in which the
  781. procedure _msg2 lies. Relocatable data is explicitly defined in an object
  782. module and will not be mistakenly interpreted as machine instructions.
  783. Relocatable code segment data does not require a non parseable
  784. declaration for the object module in which it resides. It is possible  to
  785. determine if code segment data is relocatable by inspecting the assembler
  786. output list file. This file includes relocatable information in the machine
  787. code portion of the listing.
  788.  
  789. - no non contiguous instruction addresses in code segment
  790.  
  791. The occurrence of a non contiguous instruction address in a parseable
  792. object module will cause PC_Opt to terminate execution. The use of the
  793. assembly language ORG pseudo op in a code segment, for example,  will
  794. generate a non contiguous instruction address. This pseudo op causes the
  795. next instruction to begin at the address specified rather than at the address
  796. following the previous instruction. All object modules that contain a non
  797. contiguous instruction address must be declared as non parseable. 
  798.  
  799.                      Example:
  800.  
  801.                      _nearp         proc   near
  802.                             push    bp
  803.                             mov     bp,sp
  804.                             ---
  805.                             ---
  806.                             pop     bp
  807.  
  808.                             retf
  809.                             ORG     $ - 1
  810.                             ret
  811.                      _nearp         endp
  812.  
  813. Procedure _nearp contains an ORG statement that sets the next instruction
  814. to begin before the previous retf instruction. This overwrites the far return
  815. instruction with the subsequent near return instruction.
  816.  
  817. This non contiguous addressing is not supported by PC_Opt and will
  818. terminate execution unless the object module that contains procedure
  819. _nearp is declared as non parseable.
  820.  
  821. - protected mode and 32 bit instructions not supported
  822.  
  823. Protected mode instructions and 32 bit instructions are currently not
  824. supported in parseable object modules. These instructions will cause a
  825. "immediate data found in code segment" fatal error. All object modules
  826. that contain these type of instructions must be declared as non parseable.
  827.  
  828. - non standard call and return operations
  829.  
  830. Any substitution of a return or call instruction by its equivalent series of
  831. jump operations in an object module would require a non parseable
  832. declaration for that object module. The following two examples illustrate
  833. this type of substitution.
  834.  
  835.                      Example:
  836.  
  837.                      A1:    dw   ?
  838.                      _jumpret       proc   near
  839.                             pop     cs:A1
  840.                             ---
  841.                             ---
  842.                             jmp     word ptr cs:A1
  843.                      _jumpret       endp
  844.  
  845. In the previous example the procedure return address is popped off of the
  846. stack and stored in the variable A1. The last instruction in the procedure
  847. transfers control back to the procedure return address through the A1
  848. variable. This illustrates a method of substituting a return statement with
  849. an indirect jump. 
  850.  
  851.                      Example:
  852.  
  853.                      _proca         proc   far
  854.                             push    bp
  855.                             mov     bp,sp
  856.                             ___
  857.                             ___
  858.                             pop     bp
  859.                             retf
  860.                      _proca         endp
  861.  
  862.                      _jumpcall      
  863.                             proc    far
  864.                             push    bp
  865.                             mov     bp,sp
  866.                             ---
  867.                             ---
  868.                             push    cs
  869.                             mov     ax,offset pastcall
  870.                             push    ax
  871.                             jmp     near ptr _proca
  872.                      pastcall:
  873.                             ___
  874.                             ___
  875.                             pop     bp
  876.                             retf
  877.                      _jumpcall      endp
  878.  
  879. In this example procedure _jumpcall contains a series of instructions
  880. leading up to a transfer of control to _proca. These instructions perform
  881. the same operations as a single call instruction. The push cs and push ax
  882. instructions store the return segment and offset address on the stack. The
  883. jump to _proca will then result in a return of control to the address of the
  884. following instruction. This illustrates an example of substituting a call
  885. statement with a direct jump. 
  886.  
  887. The previous examples are certainly not representative of commonplace
  888. coding techniques but nonetheless illustrate restrictions placed upon
  889. parseable object modules. CHAPTER 5   PC_Opt OPTIMIZATIONS
  890.  
  891. This section describes the various optimizations performed by PC_Opt.
  892. The stack clearing and register passing conversions may be disabled by
  893. command line options.
  894.  
  895. Far to Near Calling Conversion
  896.  
  897. The entire program calling hierarchy is analyzed and far call and return
  898. instructions are converted to their near counterparts if possible. This
  899. involves creating new code segments that contain the calling and called
  900. code. The contents of these new segments can be inspected by viewing the
  901. output map file from the subsequent link. This conversion produces
  902. smaller and more efficient executable code. 
  903.  
  904. Register Passing Conversion
  905.  
  906. Stack based procedure parameters can be converted to register parameters
  907. in some instances. This conversion will result in a reduction in the number
  908. of memory accesses performed during program execution. 
  909.  
  910. Unreachable Procedure Deletion
  911.  
  912. Object modules may contain procedures that are not accessed by any
  913. calling code. Normally these non accessed procedures would be linked
  914. into the final executable file even though they are never invoked. PC_Opt
  915. determines which procedures are not accessed and deletes them from the
  916. output object module. This deletion produces a reduced executable code
  917. size.  
  918.  
  919. Stack Clearing Conversion
  920.  
  921. In allowing for a variable number of arguments to be passed into a
  922. function, the C language definition necessitates that object code be
  923. generated in compliance with the C language calling convention.
  924.  
  925. This convention requires that the calling code is to perform all parameter
  926. stack clearing operations after return of control from the called function.
  927. Calling code parameter stack clearing requires additional instructions when
  928. compared to called procedure parameter stack clearing. Called procedure
  929. parameter stack clearing is sometimes referred to as the pascal stack
  930. clearing convention. PC_Opt converts object code to the shorter called
  931. procedure stack clearing format wherever possible. This conversion results
  932. in smaller and more efficient executable code.
  933.  
  934. NOP Instruction Deletion
  935.  
  936. The nop instruction is usually inserted by compilers to replace the last
  937. byte in a 3 byte jump instruction when the compiler is able to convert the
  938. jump to a jump short instruction. In some cases this instruction is placed
  939. into object code as filler in order to allow destination addresses to fall on
  940. even code boundaries. 
  941.  
  942.  
  943. This even destination alignment offers a slight improvement in execution
  944. speed over non aligned code. Unfortunately PC_Opt does not contain any
  945. even code alignment capabilities. Because of this, all nop instructions are
  946. removed from edited code due to the fact that their edited alignment may
  947. have been altered to an odd code address.
  948. CHAPTER 6   THIRD PARTY OBJECT LIBRARIES
  949.  
  950. If third party object modules or libraries are included as input to PC_Opt
  951. then their accompanying non parseable lists must also be included. If these
  952. lists cannot be obtained then the object module or library must be declared
  953. as non parseable. In most cases the third party object module or library
  954. will have to be declared as non parseable because information on the on
  955. the nature of its code will be difficult to obtain.
  956.  
  957. If an object library file is declared as non parseable then only the code not
  958. generated by a supported compiler is considered non parseable. PC_Opt
  959. will edit supported compiler generated code in a non parseable object
  960. library. 
  961. CHAPTER 7   PROGRAM TESTING
  962.  
  963. Extensive program testing should be performed after linking the output
  964. object files into a final executable file. All possible paths of a program
  965. should be explored in order to confirm reliability of the final product. 
  966. Most problems will arise as a result of a non parseable object module
  967. declaration being omitted. If any of omission of this type were to occur
  968. then it would be possible for the resultant output program to hang.
  969.  
  970. Full symbolic debugging information, unfortunately, is not included
  971. PC_Opt output object files. Public symbol debug information can be
  972. accessed through Borland's debugger if the /v option is enabled during
  973. linking of the PC_Opt output object files. These symbols can be accessed
  974. by using the goto address command in the debugger's CPU window. 
  975.  
  976. The following are additional program testing tips:
  977.  
  978. If the final executable code had worked previously and fails after
  979. modifications have been made to the program, attempt to determine if the
  980. specific changes made have any affect on the corresponding declaration
  981. files. It is easy to forget to perform the necessary modifications on the
  982. declaration files after modifying the source code. 
  983.  
  984. Run PC_Opt with stack clearing disabled and or register passing disabled
  985. and check if the problem is still present. If the program then executes
  986. correctly then the problem can be narrowed down to a certain operation
  987. being performed on the object code.
  988.  
  989. Run PC_Opt with the /g option if the problem persists. This will prevent
  990. the altering of any object module that was not generated by a supported
  991. compiler. If this solves the problem then the original problem is a result
  992. of failing to declare object module(s) as non parseable.  CHAPTER 8   SAMPLE RUN
  993.  
  994. A sample run is described here in order to illustrate the basic steps
  995. involved in using PC_Opt. The majority of the preparation effort involves
  996. creating the correct application declaration file for the project to be
  997. processed.
  998.  
  999. A large code model program is composed of twenty-eight object files, two
  1000. runtime object library files and a third party screen i/o object library file.
  1001. Three of the input object files are assembler generated. The others,
  1002. originating from C language source code, have been generated by
  1003. Borland's C++ compiler.
  1004.  
  1005. Since the linker will be accepting the Borland large model runtime
  1006. libraries as input, the corresponding runtime declaration file, bl.dat, is
  1007. selected for use with PC_Opt (see DISTRIBUTION DISKETTE
  1008. CONTENTS). This file contains all of the necessary non parseable
  1009. listings for the Borland large program model runtime libraries. This file
  1010. is specified with the /r command line option.
  1011.  
  1012. The next step is to create the application declaration file. This file is to
  1013. contain non parseable information corresponding to the twenty-eight
  1014. application object files and the third party object library file. 
  1015.  
  1016. One of the assembly language source files is found to contain non
  1017. relocatable immediate data within a code segment. Code segment non
  1018. relocatable immediate data requires a non parseable declaration for the
  1019. object module in which it is located. The assembly source file name that
  1020. contains this data is append.asm so the application declaration file opt.dat
  1021. is created containing append.obj comprising its non parseable list.
  1022.  
  1023. The third party object library vendor is unable to furnish all of the details
  1024. about non parseable object modules within the screen i/o library file.
  1025. Because of this, the entire library file scrio.lib is declared as non
  1026. parseable. 
  1027.  
  1028. scrio.lib is inserted into non parseable list in the application declaration
  1029. file opt.dat. 
  1030.  
  1031. Declaration file creation is now completed and the next step is to specify
  1032. the input object files and object library files in order run PC_Opt. A link
  1033. response file, enet.lrf,  has already been set up that contains a list of these
  1034. files. PC_Opt is invoked using the following command line:
  1035.  
  1036.               opt /rbl.dat @enet.lrf
  1037.  
  1038. This command line specifies for PC_Opt to be run using the Borland large
  1039. model runtime declaration file and the default application declaration file
  1040. opt.dat. 
  1041.  
  1042. PC_Opt processing is initiated and execution completes successfully. The
  1043. program generates an object file for each object module that is to be
  1044. linked into the final executable file. A link response file, OPT.LRF, is
  1045. also created that contains a list of these output object filenames. The
  1046. Borland linker, tlink, is invoked with the following command line in order
  1047. to produce the final executable file:
  1048.  
  1049.               tlink @opt.lrf
  1050.  
  1051. This will produce the desired ouput executable file. APPENDIX A  ERROR MESSAGES
  1052.  
  1053. 201    end of file not expected - filename XXXXXXXX
  1054.        An end of file condition has been detected and additional expected
  1055.        items have not been read.
  1056.  
  1057. 202    io error reading/writing file XXXXXXXX
  1058.        An IO error occurred while reading or writing a file. 
  1059.  
  1060. 203    exe extension expected on executable filename XXXXXXXX
  1061.        A file extension other than exe was found on the input executable
  1062.        filename. This filename is searched for in the specified makefile
  1063.        in order to obtain the list of input object files.
  1064.  
  1065. 204    colon expected after executable filename XXXXXXXX in
  1066.        makefile XXXXXXXX
  1067.        An executable filename was found in column 1 in a makefile but
  1068.        no following colon has been encountered. (see makefile input for
  1069.        further explanation).
  1070.  
  1071. 205    executable filename XXXXXXXX not found in makefile
  1072.        XXXXXXXX
  1073.        The executable filename was not found during makefile search.
  1074.        NOTE: The executable filename must start in column 1 to be
  1075.        interpreted as being dependant on following list of object files
  1076.        (thus only column 1 is searched) make sure the executable
  1077.        filename starts in column 1 (see makefile input for further
  1078.        explanation).
  1079.  
  1080. 206    no link command found for executable filename XXXXXXXX
  1081.        in makefile XXXXXXXX
  1082.        The next line in the makefile was expected to be a link command
  1083.        line for the executable filename but was not found to be indented
  1084.        so it cannot be interpreted as a link command line (see makefile
  1085.        input for a further explanation).
  1086.  
  1087. 207    no dependency object files or libraries found on link command
  1088.        line for executable file XXXXXXXX in makefile XXXXXXXX
  1089.        The link command was found for the input executable filename but
  1090.        no list of object files or object libraries were found following the
  1091.        link command and link parameter flags.
  1092.  
  1093. 208    file XXXXXXXX not found
  1094.        The file to be opened was not found.
  1095.  
  1096. 209    io error opening file XXXXXXXX
  1097.        An IO error occurred while attempting to open a file
  1098.  
  1099. 210    end of object module XXXXXXXX not expected
  1100.        An end of file condition occurred and additional object module
  1101.        data was expected.
  1102.  
  1103.  
  1104. 211    application declaration file specified and /g option enabled
  1105.        An application declaration filename was specified on the command
  1106.        line and the /g option was also enabled. The /g command line
  1107.        option specifies that the application declaration file is to be
  1108.        ignored.
  1109.  
  1110. 221    obj or lib extension expected in filename XXXXXXXX in
  1111.        declaration file XXXXXXXX
  1112.        A filename was found in a declaration file but no .lib or .obj file
  1113.        extension was present. 
  1114.  
  1115. 240    pathname too long for file XXXXXXXX
  1116.        A pathname for an input file exceeds the dos maximum allowable
  1117.        pathname length.
  1118.  
  1119. 241    object file XXXXXXXX must have an OBJ extension
  1120.        An input object file was found to have a file extension other than
  1121.        .OBJ.
  1122.  
  1123. 242    object library file XXXXXXXX must have an LIB extension
  1124.        An input object library file was found to have a file extension
  1125.        other than .LIB.
  1126.  
  1127. 243    bad record type X found in object module XXXXXXXX at
  1128.        offset 99999
  1129.        An unknown object module record type was encountered in an
  1130.        object module. This error usually indicates a damaged object
  1131.        module.
  1132.  
  1133. 244    segment name not found in object module XXXXXXXX
  1134.        The segment, segment class, or segment overlay name cannot be
  1135.        found in an object module. This error indicates a damaged object
  1136.        module.
  1137.  
  1138. 245    illegal group component type X in object module XXXXXXXX
  1139.        The group component byte in a group definition record in an
  1140.        object module is not the required 0xFF value. This error indicates
  1141.        a damaged or unsupported type object module.
  1142.  
  1143. 246    group segment not found in object module XXXXXXXX
  1144.        A segment index that is part of a group definition has no matching
  1145.        segment definition in an object module. This error indicates a
  1146.        damaged object module.
  1147.  
  1148. 247    group name not found in object module XXXXXXXX
  1149.        A name index that is part of a group definition has no matching
  1150.        name definition in an object module. This error indicates a
  1151.        damaged object module.
  1152.  
  1153. 248    data segment not found in object module XXXXXXXX
  1154.        A segment index that is part of a data record has no matching
  1155.        segment definition in an object module. This error indicates a
  1156.        damaged object module. This also may indicate a C++ language
  1157.        object module.
  1158.  
  1159. 249    iterated data found in code segment in object module
  1160.        XXXXXXXX
  1161.        Iterated data was found in a code segment. This prevents
  1162.        successful instruction parsing of the object module. This object
  1163.        module must be declared as non parseable using the in a
  1164.        declaration file.
  1165.  
  1166. 250    80386 record found in object module XXXXXXXX not
  1167.        supported
  1168.        An 80386 object module record was found. 80386 object modules
  1169.        are  presently not supported.
  1170.  
  1171. 251    BAKPAT fixup record found in object module XXXXXXXX
  1172.        not supported
  1173.        A Quick C BAKPAT fixup object module record was found. This
  1174.        type of fixup record is used for single pass compiling and is
  1175.        currently not supported.
  1176.  
  1177. 252    MSC 7.0 object file record type X found in object module
  1178.        XXXXXXXX not supported
  1179.        A Microsoft C version 7.0 object module record was found. The
  1180.        current version of PC_Opt does not support this record type.
  1181.  
  1182. 253    invalid library header record found in object library
  1183.        XXXXXXXX
  1184.        The expected library header record (record type 0xF0) was not
  1185.        found at the beginning of a object library file. This indicates a
  1186.        damaged object library file.
  1187.  
  1188. 254    duplicate public XXXXXXXX found in object library
  1189.        XXXXXXXX
  1190.        A public symbol was found more than once in an object library 
  1191.        dictionary. This indicates a damaged object library file.
  1192.  
  1193. 255    object module header not found in library XXXXXXXX for
  1194.        public symbol XXXXXXXX
  1195.        The expected object module header record (record type 0x80) was
  1196.        not found at the beginning of a object module in an object library
  1197.        file. This indicates a damaged object library file.
  1198.  
  1199. 256    unresolved external reference XXXXXXXX
  1200.        An external symbol was found with no matching public symbol
  1201.        present in any of the input object or object library files.
  1202.  
  1203. 257    fixup location exceeds code segment size in object module
  1204.        XXXXXXXX
  1205.        A fixup location extends beyond the end of code segment data in
  1206.        an object module. This usually indicates a damaged object module.
  1207.  
  1208. 258    fixup destination exceeds code segment size in object module
  1209.        XXXXXXXX
  1210.        A fixup destination extends beyond the end of code segment data
  1211.        in an object module. This usually indicates a damaged object
  1212.        module.
  1213.  
  1214. 259    immediate data found in code segment in object module
  1215.        XXXXXXXX
  1216.        Immediate data was found while parsing instructions in a code
  1217.        segment. Object modules that contain immediate data in code
  1218.        segments must be declared as non parseable using the -N
  1219.        parameter.
  1220.  
  1221. 260    fixup external index 99 not found in object module
  1222.        XXXXXXXX
  1223.        An external index derived from a fixup record has no matching
  1224.        external symbol in an object module. This is an indication of a
  1225.        damaged object module.
  1226.  
  1227. 261    group based fixup target in code segment in object module
  1228.        XXXXXXXX
  1229.        A fixup target that refers to a location in a code segment is found
  1230.        to be an offset to a group of segments rather than a single
  1231.        segment. This mode of target referencing is not supported.
  1232.  
  1233. 262    absolute displacement exceeds segment size in object module
  1234.        XXXXXXXX
  1235.        A non fixup displacement refers to a destination beyond the end of
  1236.        a code segment. This is usually an indication of a damaged object
  1237.        module.
  1238.  
  1239. 263    fixup not found on second pass in object module XXXXXXXX
  1240.        A fixup table has been corrupted between first and second pass of
  1241.        instruction parsing. This is a diagnostic error and will be removed
  1242.        upon completion of beta testing.
  1243.  
  1244. 264    fixup target segment 99 not found in object module
  1245.        XXXXXXXX
  1246.        A segment index derived from a fixup record has no matching
  1247.        segment record in an object module. This is an indication of a
  1248.        damaged object module.
  1249.  
  1250. 265    absolute intersegment addressing in object module
  1251.        XXXXXXXX
  1252.        No matching fixup can be found for an intersegment address. This
  1253.        usually is an indication of a damaged object module.
  1254.  
  1255. 266    public XXXXXXXX offset exceeds size of segment in object
  1256.        module XXXXXXXX segment index 9999 offset 99999
  1257.        A public symbol has been found in a segment but has an offset that
  1258.        exceeds the size of that segment. This is an indication of a
  1259.        damaged object module.
  1260.  
  1261. 267    non contiguous data in code segment found in object module
  1262.        XXXXXXXX not supported
  1263.        A code segment was found to contain non contiguous data. This
  1264.        condition occurs for instance when an ORG statement in assembly
  1265.        language sets an instruction address to a designated value. An
  1266.        object module that contains non contiguous data in a code segment
  1267.        must be defined as non parseable.
  1268.  
  1269. 268    code segment data record exceeds segment length in object
  1270.        module XXXXXXXX
  1271.        A code segment data record was found that exceeds the size listed
  1272.        in the corresponding segment record. This indicates a damaged
  1273.        object module.
  1274.  
  1275. 269    list locked when not in use in object module XXXXXXXX
  1276.        A list that has been processed has not been unlocked. This is an
  1277.        internal paging error.
  1278.  
  1279. 270    fixup references code segment comdef symbol XXXXXXXX in
  1280.        object module XXXXXXXX
  1281.        A direct transfer external fixup found in a code segment refers to
  1282.        a common type symbol. Code segment common symbols are not
  1283.        supported in direct transfer instructions.
  1284.  
  1285. 271    inconsistent results derived while consolidating code
  1286.        Errors occurred while analyzing procedure relationships. This
  1287.        error indicates a discrepancy between optimization analysis results
  1288.        between related procedures.
  1289.  
  1290. 272    multiple program starting addresses found in object modules
  1291.        XXXXXXXX and XXXXXXXX
  1292.        More than 1 program starting address was found in input object
  1293.        modules.
  1294.  
  1295. 273    no program starting address found in object modules
  1296.        No program starting address was found in the input object
  1297.        modules.
  1298.  
  1299. 274    far call found in object module XXXXXXXX offset 99999 calls
  1300.        near procedure in object module XXXXXXXX offset 99999
  1301.        A far call (either call far ptr or push cs, call near ptr) calls a
  1302.        procedure that contains a terminating near return instruction. If this
  1303.        non conventional call is intentional then the object module that
  1304.        contains either the calling procedure or the called procedure must
  1305.        be declared as non parseable in order for PC_Opt processing
  1306.        complete successfully.
  1307.  
  1308. 275    near call found in object module XXXXXXXX offset 99999
  1309.        calls far procedure in object module XXXXXXXX offset 99999
  1310.        A near call (call near ptr) calls a procedure that contains a
  1311.        terminating far return instruction. If this non conventional call is
  1312.        intentional then the object module that contains either the calling
  1313.        procedure or the called procedure must be declared as non
  1314.        parseable in order for PC_Opt processing complete successfully. 
  1315.  
  1316.        This error might be the result of a far call instruction sequence
  1317.        consisting of a push cs, near call in which the push cs instruction
  1318.        does not immediately precede the call instruction. EXAMPLE -
  1319.        The following call to procedure _wayfar is meant to be a far call 
  1320.        consisting of a push cs and near call instruction sequence. The call
  1321.        is not recognized as a far call because the push cs instruction does
  1322.        not immediately precede the call instruction:
  1323.  
  1324.                      _TEXT segment byte public 'CODE'
  1325.                      _wayfar        proc   far
  1326.                             ___ 
  1327.                             ___
  1328.                             ___
  1329.                             retf
  1330.                      _wayfar        endp
  1331.  
  1332.  
  1333.                      _callwayfar    proc   far
  1334.                             push    bp
  1335.                             mov     bp,sp
  1336.                             push    si
  1337.                             mov     ax,word ptr[bp+6]
  1338.                             ___
  1339.                             ___
  1340.                             push    cs            ; push cs for intra
  1341. segment 
  1342.                                                   ;  call to far proc
  1343.                             mov     si,ax         ; save contents of ax
  1344. in si 
  1345.                                                   ;  across proc call
  1346.                             call    near ptr _wayfar
  1347.                             mov     ax,si         ; retrieve contents of
  1348. ax
  1349.                             ___
  1350.                             ___
  1351.                             ___
  1352.                             pop     si
  1353.                             pop     bp
  1354.                             retf
  1355.                      _callwayfar    endp
  1356.                      _TEXT          ends
  1357.  
  1358. 276    external symbol XXXXXXXX referenced in object module
  1359.        XXXXXXXX not found in code segment in object module
  1360.        XXXXXXXX
  1361.        An external symbol that was expected to reference a code segment
  1362.        public symbol references a non code segment public symbol.
  1363.  
  1364. 277    add byte ptr [bx+si],al instruction found in code segment in
  1365.        object module XXXXXXXX.
  1366.        add byte ptr [bx+si],al instruction was found during instruction
  1367.        parse. This instruction is composed of bytes 00 00 and is therefore
  1368.        suspected as being data rather than a true instruction. Use the /z
  1369.        command line parameter in order to allow this instruction to be
  1370.        parsed.
  1371.  
  1372. 278    conditional transfer instruction found at end of code segment
  1373.        in object module XXXXXXXX
  1374.        A conditional transfer instruction was found to be the last opcode
  1375.        in a code segment. This is not allowed in parseable object
  1376.        modules.
  1377.  
  1378. 280    hard disk paging error
  1379.        An IO error occurred while attempting to page data out to disk.
  1380.  
  1381. 281    expanded memory paging error
  1382.        An IO error occurred while attempting to page data out to
  1383.        expanded memory.
  1384.  
  1385. 282    invalid page address
  1386.        An attempt was made to page out or page in data from an
  1387.        uninitialized page address. This is a diagnostic error and will be
  1388.        removed after beta testing.
  1389.  
  1390. 283    no more page memory available
  1391.        An attempt was made to page out data and no disk or expanded
  1392.        memory was available. Attempt to increase available disk space
  1393.        and rerun the program.
  1394.  
  1395. 284    undefined paging status
  1396.        An unknown paging error occurred. This is an indication of
  1397.        internal error.
  1398.  
  1399. 285    out of memory
  1400.        All of RAM memory has been used up and no more is available.
  1401.        Disable all TSR's, device drivers, network drivers, shells, etc. and
  1402.        attempt to rerun program.
  1403.  
  1404. 286    internal memory block too large for object module
  1405.        XXXXXXXX
  1406.        An object module is too large to fit data into a memory block.
  1407.        Attempt to split the object module into separate smaller object
  1408.        modules and attempt to rerun program.
  1409.  
  1410. 287    illegal maximum segment size 99999 specified on command line
  1411.        A maximum segment size was specified which exceeds 65535 or
  1412.        is less than 2000 bytes.
  1413.  
  1414. 288    unrecognized command line argument XXXXXXXX
  1415.        A command line argument was found that is not recognized as a
  1416.        legal command line argument.
  1417.  
  1418. 289    object files specified in makefile XXXXXXXX and on command
  1419.        line
  1420.        Command line input object files are specified along with makefile
  1421.        object module specification. Input object files cannot be specified
  1422.        in both a makefile and on the command line.
  1423.  
  1424. 290    makefile specified but no executable file specified
  1425.        A makefile was specified on the command line but no
  1426.        accompanying executable file was specified.
  1427.  
  1428. 293    executable string record found in object module XXXXXXXX
  1429.        not supported
  1430.        An executable string (EXESTR) record type was found in an
  1431.        object module. Executable string record types are currently not
  1432.        supported.
  1433.  
  1434. 294    weak or lazy extern record found in object module
  1435.        XXXXXXXX not supported
  1436.        A weak or lazy extern record type was found in an object module. 
  1437.        Weak or lazy extern record types are currently not supported.
  1438.  
  1439. 295    windows record found in object module XXXXXXXX. windows
  1440.        processing not enabled
  1441.        A windows record type was found in an object module. Windows
  1442.        applications are currently not supported.
  1443.  
  1444. 296    incremental compilation record found in object module
  1445.        XXXXXXXX not supported
  1446.        An incremental compilation (Quick C) record type was found in an
  1447.        object module. Quick C object modules are currently not
  1448.        supported.
  1449.  
  1450. 297    bad checksum found in object module XXXXXXXX
  1451.        A bad checksum was found in an object module record. This
  1452.        indicates a damaged object module.
  1453.  
  1454. 298    non floating point absolute data fixup found in code segment in
  1455.        object module XXXXXXXX
  1456.        Code generated by floating point operations may possibly contain
  1457.        absolute data fixups that provide for link time generation of
  1458.        floating point object code instructions. PC_Opt supports this code
  1459.        generation mechanism for floating point instructions only. All non
  1460.        floating point instruction generation of this type will generate this
  1461.        error message. If this error message occurs then the object module
  1462.        listed in the error message must be declared as non parseable.  WARNING MESSAGES
  1463.  
  1464. 201    cs override string instruction found in segment XXXXXXXX in
  1465.        object module XXXXXXXX
  1466.        A code segment override byte was found before a string instruction
  1467.        during instruction parsing. movs, cmps, scas, lods and stos are
  1468.        the five string instructions. cs override instructions prohibit the
  1469.        optimization of all procedures within a code segment.
  1470.  
  1471. 202    cs override indexed memory access found in segment
  1472.        XXXXXXXX in object module XXXXXXXX
  1473.        A code segment override byte was found before an instruction that
  1474.        contains an indexed memory access. cs override instructions
  1475.        prohibit the optimization of procedures within a code segment.
  1476.  
  1477. 203    duplicate object filename XXXXXXXX found
  1478.        An object filename appears more than once among the list of input
  1479.        object files.
  1480.  
  1481. 204    duplicate library filename XXXXXXXX found
  1482.        An object library filename appears more than once among the list
  1483.        of input object library files.
  1484.  
  1485. 205    both return statement and calling code clear stack for
  1486.        procedure number 99 segment XXXXXXXX in object module
  1487.        XXXXXXXX
  1488.        A procedure was found that contains a retn stack clearing return
  1489.        statement and calling code to that procedure was found to perform
  1490.        stack clearing operations also. This could be the result of
  1491.        compiling the called procedure with pascal type calling conventions
  1492.        and failing to do similarly when compiling the calling code.
  1493.  
  1494. 206    procedure consolidation size calculation incorrect for object
  1495.        module XXXXXXXX segment number 9999 procedure offset
  1496.        999999
  1497.        The size of a procedure calculated during segment consolidation
  1498.        analysis does not match the actual size of the procedure after
  1499.        object code editing.
  1500.  
  1501. 207    8 bit displacement converted to 16 bit displacement
  1502.        An instruction that contains an 8 bit displacement was converted
  1503.        to an equivalent instruction sequence containing a 16 bit
  1504.        displacement. 
  1505.  
  1506.        In certain instances, instruction bytes are added to object code after
  1507.        consolidating code into a segment. If these extra instruction bytes
  1508.        result in an 8 bit displacement adjustment exceeding 8 bit range
  1509.        limitations then the 8 bit displacement instruction is replaced by a
  1510.        logically equivalent instruction sequence containing a 16 bit
  1511.        displacement.
  1512.  
  1513. 208    non parseable object module XXXXXXXX listed in declaration
  1514.        file not found
  1515.        An object module or object module library was found listed in the
  1516.        non parseable list of the application declaration file but is not
  1517.        found in any of the object modules to be included in the executable
  1518.        file. This warning message is intended to alert the user of possible
  1519.        inaccuracies in the application declaration file. APPENDIX B  COMMON QUESTIONS
  1520.  
  1521. preserving near calls
  1522.  
  1523. How can it be ensured that a specified procedure or group of procedures
  1524. will be consolidated so that they transfer control to each other by near
  1525. calls and returns?
  1526.  
  1527. The set of procedures must be setup as near in the original C or assembly
  1528. source file. PC_Opt does not convert any near procedures to far
  1529. procedures, so the intra segment relationship between the procedures will
  1530. remain preserved.
  1531.  
  1532. why no link
  1533.  
  1534. Why doesn't PC_Opt additionally link the input object code in order to
  1535. produce a final executable file?
  1536.  
  1537. The overall purpose of PC_Opt is improve the quality of the object code
  1538. prior to linking. All development efforts have been directed toward this
  1539. purpose. Additional memory would be required in which to fit the linker
  1540. code which might prohibit the processing of larger programming projects.
  1541. Also, the user's normal full featured linker would in all probability
  1542. possess features that could not be included in a back end PC_Opt link
  1543. process.
  1544.  
  1545. full declaration pathnames
  1546.  
  1547. In what cases are full pathnames required for files listed in non parseable
  1548. declarations?
  1549.  
  1550. Full pathnames are required for all standalone object and object library
  1551. files listed in non parseable listings. Pathnames must not present,
  1552. however, for object module names that are contained within an object
  1553. library file. All runtime declaration files contain the default installation
  1554. pathnames for the supported compilers' runtime libraries (\borland\lib\).
  1555. These declaration files must be altered in the event that the runtime
  1556. libraries do not reside in the default pathname directories.
  1557.  
  1558. examining segment contents
  1559.  
  1560. How can the contents of the newly created code segments be examined?
  1561.  
  1562. The link map file can be inspected in order to determine which public
  1563. symbols have been consolidated into a segment. Use the /m map file
  1564. option when invoking the Borland linker.
  1565.  
  1566. program interruption
  1567.  
  1568. Can PC_Opt processing be canceled prior to normal program termination?
  1569.  
  1570. The user may cancel processing by pressing control-C. This will delete all
  1571. page files on disk and/or release paging memory being used. If for some
  1572. reason, processing is abnormally terminated by a system hang or power
  1573. interruption then the chkdsk should be run in order to freeup all disk
  1574. paging files. Run chkdsk with the /f option and delete the recovered
  1575. clusters by issuing a del \*.chk command.
  1576.  
  1577. INDEX
  1578.  
  1579. 32 bit applications            2  org psuedo op                           17
  1580. 32 bit instructions           17  OS/2                                     2
  1581. additional operations         20  parseable object modules                13
  1582. command line options           4  pascal
  1583. -axxxx                         4         stack clearing                6, 20
  1584. -b                             6  protected mode                          17
  1585. -c                             7  relocatable data                        16
  1586. -d99999                        6  runtime declaration files                2
  1587. -exxxx                         6  standard stack frames                   13
  1588. -lxxxx                         5  supported compilers                      2
  1589. -mxxxx                         6  switch statement                        15
  1590. -n                             7  system requirements                      1
  1591. -oxxxx                         5  third party object libraries        22, 24
  1592. -rxxxx                         4  windows applications                     2
  1593. -sxxxx                         5
  1594. -t                             7
  1595. -z                             7
  1596. /g                             7
  1597. declaration file comments     12
  1598. declaration files              2
  1599. creating                      11
  1600. non parseable information     11
  1601. diskette contents              2
  1602. extended libraries             2
  1603. immediate data                15
  1604. input object modules
  1605. command line input             8
  1606. linker responsefile input      8
  1607. makefile input                 9
  1608. specifying                     8
  1609. third party                    2
  1610. near call preservation        38
  1611. non contiguous instructions   17
  1612. non parseable declaration     11
  1613. non standard calls            18
  1614. non standard returns          18
  1615. nop instruction               21
  1616. optimizations
  1617. calling conversion            20
  1618. code deletion                 20
  1619. register passing              20
  1620. stack clearing                20
  1621.                                        
  1622.                                        
  1623.