home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 5 / 05.iso / a / a012 / 1.ddi / CONDLINK.TXT < prev    next >
Encoding:
Text File  |  1991-05-01  |  8.6 KB  |  226 lines
  1.                          5 FOCUS: Conditional Linking
  2.                                by Roger Donnay
  3.  
  4.  
  5. Introduction
  6.  
  7. By now you are probably quite familiar with the features of the
  8. Clipper 5 preprocessor which allow "conditional compiling".  Of
  9. course, this is a very handy method of controlling the configuration
  10. of your application, but many times it is simpler to use CONDITIONAL
  11. LINKING methods instead.
  12.  
  13. Through Conditional Linking, you can control the symbols and or code
  14. segments which get linked into your application by using special
  15. RTLINK commands.  Many times it is easier to control the configuration
  16. of a large application at "link-time" rather than "compile-time".
  17. This can be accomplished by using RTLINK's DEFINE command and/or REFER
  18. command.
  19.  
  20.  
  21. The DEFINE Command
  22.  
  23. DEFINE <symbol> lets you force a "null address" to be assigned to any
  24. symbol and prevent that symbol or "function" and its associated code
  25. from being linked into your application.  An example of using DEFINE
  26. for conditional linking could be shown as follows:
  27.  
  28.   * Your Clipper code
  29.   DO menu
  30.   DO CASE
  31.       CASE choice=1
  32.           DO report1
  33.       CASE choice=2
  34.           DO report2
  35.       CASE choice=3
  36.           DO report3
  37.   ENDCASE
  38.  
  39.   * Your link script file
  40.   DEFINE report2,report3
  41.  
  42. In the above example, the command DEFINE report2,report3 will insure
  43. that the REPORT2 and REPORT3 programs do not get linked into the
  44. program.  This allows you to build test versions of your application
  45. and only link in the portions you are currently testing.  This
  46. conditional linking technique provides the following advantages:
  47.  
  48.   1. Reduces the .EXE physical size.
  49.  
  50.   2. Improves the memory model of the program by removing unneeded
  51.      code and symbols.
  52.  
  53.   3. Improves linking speed.
  54.  
  55.   4. Can be accomplished without the need to re-compile your code.
  56.  
  57. DEFINE can also be used to resolve "Undefined Symbol" errors produced
  58. during linking.  For example, let's say you inherited a clipper
  59. program which calls a specified function in a third-party library.
  60. You don't happen to have the library so RTLINK will generate
  61. "Undefined Symbol" errors indicating that it could not find the symbol
  62. you have referenced in your application.  Of course, if the function
  63. is an important integral part of the application and the application
  64. cannot even start without it, then you must resolve the problem by
  65. acquiring the proper library.
  66.  
  67. There are many other cases, however, in which the symbol is not
  68. important to you at the current time and you may be only interested in
  69. running portions of the program in which this symbol is not used.  In
  70. cases such as these, simply use the command DEFINE <symbol> in your
  71. link script file to eliminate the link errors.
  72.  
  73.  
  74. The REFER Command
  75.  
  76. The REFER <symbol> command in your RTLINK script file performs the
  77. same function as the EXTERNAL <symbol> command in your source code.
  78. So why use REFER instead?  Because, again, configuration control can
  79. be accomplished at link-time rather than compile-time.  For this
  80. example, I'm going to use my product dCLIP as an example of how
  81. important this command is used to determine the configuration of a
  82. large Clipper application.
  83.  
  84. dCLIP is a database management tool and development platform which
  85. supports a large variety of features which are all callable by
  86. commands or functions from our main dot-prompt. There are times that
  87. the dCLIP programmer wishes to create a "stripped-down" version or
  88. "subset" of the dot-prompt commands when linking the DC_DOT() function
  89. into their application.  For example, it may not be desirable to
  90. include the report manager, printer manager, import/export utilities,
  91. assist system, etc.
  92.  
  93. The hard way to accomplish this task is to modify the source code,
  94. recompile it and use the modified code rather than the code in the
  95. dCLIP library.  Wouldn't it be much simpler if the list of desired
  96. programs to link could be handled by a simple table in the link
  97. script?  Look at the advantages:
  98.  
  99.   1. No need to modify source code.
  100.  
  101.   2. No need to produce different sets of object files or libraries.
  102.  
  103.   3. Only one file, the link-script, needs to be modified.
  104.  
  105. There is one thing that must be done during programming to give you
  106. this flexibility: Make sure that the programs called by your menus or
  107. commands are called by "indirect reference".   The simplest example of
  108. an indirect call is a procedure that is called via macro as follows:
  109.  
  110.   program = "REPORT1"
  111.   DO &program
  112.  
  113. The indirect reference insures that the REPORT1 symbol is not created
  114. at compile-time so you can instead force this symbol at link-time.
  115. When the above code is compiled and linked there will be no symbol
  116. created for the linker so that the procedure REPORT1 will not be
  117. linked into the program.  Now you can make the decision at link-time
  118. to decide if you want REPORT1 to be linked into your application by
  119. using the following command:
  120.  
  121.   REFER REPORT1
  122.  
  123. Of course, if you don't include the above command, the REPORT1 module
  124. will NOT be linked into the program thereby causing a runtime error in
  125. the event that the operator chooses the menu item which selects the
  126. REPORT1 module.  In dCLIP, we handle this problem by calling all major
  127. programs or functions through our DC_DO() function.  DC_DO() is a more
  128. user-friendly way of handling these situations by allowing you to
  129. selectively decide the features of your end application at link-time.
  130. If a procedure or function is accessed indirectly via DC_DO() then the
  131. operator is given a friendly message rather than a runtime error
  132. message in the event that you choose not to link the selected module.
  133.  
  134. The DC_DO() function source code:
  135.  
  136. FUNCTION dc_do
  137. PRIVATE _d_c_para, _d_c_doscr, _d_c_1obj, _d_c_c, _d_c_func, ;
  138.         _d_c_doprg, _d_c_pcall
  139. PARAMETERS _d_c_doprg, _d_c_pcall
  140. _d_c_pcall = IIF(TYPE('_d_c_pcall') = 'C', _d_c_pcall, '')
  141. _d_c_doprg = IIF(TYPE('_d_c_doprg') = 'C', _d_c_doprg, '')
  142. _d_c_para = PCOUNT()
  143. _d_c_func = _d_c_doprg
  144. IF '(' $ _d_c_doprg
  145.   _d_c_doprg = SUBSTR(_d_c_doprg, 1, AT('(', _d_c_doprg) - 1)
  146. ENDIF
  147. * check to see if called function or procedure is in memory
  148. IF TYPE(_d_c_doprg + '()') # 'UI'
  149.   IF EMPTY(_d_c_pcall)
  150.     _d_c_c = SETCOLOR()
  151.     _d_c_doscr = DC_EXPLODE(10, 5, 17, 75)
  152.     @ 11,21 SAY 'Sorry, this configuration of dCLIP does not include the'
  153.     @ 12,21 SAY 'selected procedure or function.  Include the command'
  154.     @ 13,21 SAY 'EXTERNAL '+_d_c_doprg+' in your program source code or'
  155.     @ 15,21 SAY 'REFER '+_d_c_doprg+' in your link file if you wish to'
  156.     @ 16,21 SAY 'include this function.'
  157.     INKEY(0)
  158.     DC_IMPLODE(_d_c_doscr)
  159.     RETURN .f.
  160.   ELSE
  161.     RETURN DC_DO(_d_c_pcall)
  162.   ENDIF
  163. ENDIF
  164. IF '(' $ _d_c_func
  165.   RETURN &_d_c_func
  166. ELSE
  167.   DO &_d_c_doprg
  168. ENDIF
  169. RETURN .t.
  170.  
  171. Using DC_DO() in your application code:
  172.  
  173.   * Your Clipper code
  174.   DO menu
  175.   DO CASE
  176.       CASE choice=1
  177.           DC_DO('report1')
  178.       CASE choice=2
  179.           DC_DO('report2')
  180.       CASE choice=3
  181.           DC_DO('calc()')
  182.   ENDCASE
  183.  
  184.  
  185. Quicker Linking
  186.  
  187. During programming sessions you are usually working on a small portion
  188. of your application at any one time, yet each time you relink the
  189. application you must relink all of your executable code.  In previous
  190. articles I have discussed using PLL's and "incremental linking" to
  191. improve this process. However, in many situations conditional linking
  192. can be even more effective.  By adding DEFINE <symbol> commands in
  193. your link script file, you can effectively prevent the linking of all
  194. code that is associated with the defined symbol.  By adding a large
  195. group of DEFINE commands you can eliminate the linking of a major
  196. portion of the application.  During testing it is necessary to link
  197. only the code you are testing, not all menus and submenus, so use the
  198. DEFINE command to strip out the code you don't need.   You will get a
  199. smaller .EXE, a smaller memory model and the program will even
  200. start up faster.
  201.  
  202.  
  203. Conclusion
  204.  
  205. Conditional linking is an alternative method of application
  206. configuration control which can make application development much
  207. easier to manage. Take the time to experiment with this method.  If
  208. you produce a Clipper add-on library, you may find this technique to
  209. be invaluable.
  210.  
  211.  
  212. About the Author
  213.  
  214. Roger Donnay is the developer of the dCLIP development platform/
  215. runtime system for Clipper, and the application libraries SOFT.CLIP
  216. and TIME-TRAK. He will be a featured speaker at the Nantucket
  217. Developers Conference in June.  Feel free to contact Roger via the
  218. Aquarium Message Center, or at:
  219.  
  220. DONNAY Software Designs
  221. 1880 Park Newport, #104
  222. Newport Beach, CA 92660
  223. Tel: 714-721-6720
  224. Fax: 714-721-9495
  225. Compuserve: 73227,1225
  226.