home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / pcmag / chain_4.arc / CHAIN.DOC < prev    next >
Text File  |  1987-11-17  |  9KB  |  186 lines
  1.                      Chain Facility for Turbo Pascal 4.0
  2.                                  Version 1.0
  3.                                   11/17/87
  4.                                 Kim Kokkonen
  5.  
  6. Overview
  7. ------------------------------------------------------------------------------
  8. Turbo Pascal 4.0 no longer supports several features that many programmers
  9. have come to count upon: Chain, Execute, and overlays. This Chain facility
  10. provides a reasonable facsimile of the Turbo 3 Chain and Execute commands.
  11. Turbo 4's smart linker raises some new issues, though: see the Restrictions
  12. and Limitations section below before getting your hopes too high.
  13.  
  14. The chain facility is implemented in a small unit that you USE in your
  15. Turbo Pascal 4.0 program. The unit exports a single function called Chain4
  16. which you call to chain to a new program. You can chain to any other EXE or
  17. COM file. Unlike Turbo 3, there is no restriction that the chained program be
  18. another Turbo Pascal program. The new program overwrites the current program
  19. in memory. Control will not return to the original program unless you chain
  20. back to it.
  21.  
  22.  
  23. Usage
  24. ------------------------------------------------------------------------------
  25. The source code for a unit named CHAIN is provided. Add this unit near the
  26. beginning of your USES statement. CHAIN depends on no other units, and uses
  27. about 400 bytes of code space. The first time you compile it, you'll need
  28. CHAIN.PAS and CHAIN.OBJ. Thereafter, you'll just need to have CHAIN.TPU to
  29. link into your program.
  30.  
  31. CHAIN exports a single function, Chain4. It is declared as follows:
  32.  
  33.   function Chain4(Path, CmdLine : string) : word;
  34.  
  35. The Path parameter to Chain4 specifies the name of the new program to execute.
  36. Path must be a complete program name, including the extension, and a drive or
  37. directory name if the file is not in the current directory. CmdLine is the
  38. equivalent of a DOS command line to pass to the new program. Due to internal
  39. limitations of CHAIN, the command line is limited to 95 characters maximum.
  40. Any longer CmdLine will be truncated to 95 characters.
  41.  
  42. If chaining occurs successfully, the function will not return. If an error
  43. occurs, Chain4 returns a DOS error code. The following error codes are those
  44. most likely to occur:
  45.  
  46.   2  File not found
  47.   30 Read fault
  48.  
  49. Beyond a certain point, Chain4 is committed to chaining and cannot return to
  50. the calling program even if an error occurs. In this case, it will simply halt
  51. and return control to DOS. The only such case we know occurs when insufficient
  52. memory is available to load the new program. If the chained program is
  53. significantly larger than the original, it would be wise to assure that
  54. sufficient memory exists before attempting to chain.
  55.  
  56. Here are some example calls to Chain4:
  57.  
  58.   Status := Chain4('MENU.EXE', '');
  59.  
  60. Chains to MENU.EXE in the current directory, passing it an empty command line.
  61. Error information, if any, is returned in the word variable Status.
  62.  
  63.   Status := Chain4('C:\BIN\TPC.EXE', 'MYPROG /M /Q /$T+');
  64.  
  65. Chains to the command line Turbo compiler, telling it to compile the program
  66. MYPROG.PAS with various options.
  67.  
  68.  
  69. Restrictions and Limitations
  70. ------------------------------------------------------------------------------
  71. CHAIN works by using DOS function 4B, subfunction 03 (load overlay) to
  72. overwrite the current code in memory and transfer control to the new program.
  73. While performing the load overlay call, CHAIN executes a number of steps:
  74.  
  75.   o All available memory is allocated to the process.
  76.   o All file handles except StdIn, StdOut, and StdErr are closed.
  77.   o Interrupt vectors 0, 2, 23h, 24h, and 75h taken over by the Turbo SYSTEM
  78.     unit are restored to their original values.
  79.   o The new command line is put in place within the PSP.
  80.   o FCB's normally initialized by the DOS loader are initialized using the new
  81.     command line.
  82.   o The machine stack is moved to the top of available memory, a step required
  83.     for the load overlay call to work reliably. The newly loaded program will
  84.     move the stack back to wherever its normal location.
  85.   o After the new program is loaded, the registers DS, ES, SS, and SP are
  86.     initialized the same way that the DOS loader normally would and control is
  87.     transferred to the entry point of the program.
  88.  
  89. CHAIN cannot handle items on the following list. It is your responsibility to
  90. take any needed action.
  91.  
  92.   o CHAIN does not fiddle with the DOS standard file handles. If standard
  93.     input or output are redirected, this will be passed on to the new program.
  94.     This may be desirable. If not, the original program should reset these
  95.     handles before chaining.
  96.   o Interrupt vectors taken over by units other than the SYSTEM unit must be
  97.     restored. In particular, The CRT unit takes over interrupt 1Bh. You can
  98.     restore it by using the DOS unit in your program, and executing the
  99.     following statement prior to chaining: SetIntVec($1B, SaveInt1B);
  100.   o Allocation changes to the main memory block (normally handled by the
  101.     DOS EXE loader) are not performed. The new process will have all available
  102.     memory when it starts up.
  103.  
  104. Because the Turbo 4 runtime library is not completely incorporated into
  105. programs as it was in Turbo 3, it is not so easy to share data between chained
  106. programs. It is very likely that the new program will overwrite the data
  107. segment of the old. Without playing further tricks, about the only information
  108. that can be passed from the original program to the new program is the DOS
  109. command line.
  110.  
  111. The trick to share data, not supplied here, can nevertheless be described
  112. fairly easily. The original program should shrink its initial allocated memory
  113. block (using DOS function 4Ah) so that sufficient free memory exists for the
  114. shared data region. Then the original program should allocate an extra block
  115. of memory (using DOS function 48h) to hold the shared data. Function 48h will
  116. return a pointer to the new block. The original program should initialize this
  117. block as desired, and then pass a pointer to it via the DOS command line. The
  118. chained program can read the pointer from the command line, and then safely
  119. refer to the shared block by using the pointer. At some time before the
  120. application finally quits to DOS, it must deallocate the shared data block
  121. (using DOS function 49h). Properly implemented, this technique does not
  122. conflict with the stack movement performed by CHAIN itself.
  123.  
  124. Chain4 is written completely in assembly language, using MASM 5.0. It will
  125. assemble using MASM 4.0 or later.
  126.  
  127.  
  128. Copyright and Acknowledgement
  129. ------------------------------------------------------------------------------
  130. The Chain Facility for Turbo Pascal 4.0 is copyright (c) 1987 by TurboPower
  131. Software. All rights reserved.
  132.  
  133. TurboPower Software hereby grants a limited license to use this software as
  134. follows:
  135.  
  136.   o The CHAIN unit and its source code may be distributed freely as long as
  137.     there is no charge, with the exception of a handling fee not to exceed $10.
  138.   o Programs using the CHAIN unit may be distributed without restriction,
  139.     commercially or otherwise.
  140.  
  141. Thanks to Ray Lambert, who showed that this function could be done in Turbo
  142. 3.0, which buoyed the morale during a few days of machine crashes while trying
  143. to make this one work.
  144.  
  145. Contact Kim Kokkonen at Compuserve account 72457,2131 with comments regarding
  146. the Chain facility.
  147.  
  148.  
  149. Advertisement
  150. ------------------------------------------------------------------------------
  151. TurboPower Software is in the business of providing powerful tools for the
  152. Turbo Pascal programmer. Our line of products for Turbo Pascal 3.0 includes
  153. the TurboPower Utilities, Turbo Extender, T-DebugPLUS, and Turbo Optimizer.
  154.  
  155. Our first product for Turbo Pascal 4.0 is Turbo Professional 4.0, a library of
  156. 400 routines to solve the most common programming problems. Professional 4.0
  157. includes units to save time and effort in the following ways:
  158.  
  159.   o CRT unit emulation, with many added features: cursor manipulation, support
  160.     for Taskview and Desqview multitaskers, screen save and restore, and more.
  161.   o Popup windows, virtual screens, and pulldown menu systems.
  162.   o Easy and reliable ways to make your program memory resident.
  163.   o Interrupt service routine handlers.
  164.   o Keyboard macros.
  165.   o Data entry routines.
  166.   o Extended and Expanded memory access.
  167.   o A complete BCD arithmetic unit, including the transcendental functions and
  168.     the Form routine.
  169.   o Sorting and searching.
  170.   o Extensive string manipulation.
  171.   o Strings longer than 255 characters.
  172.   o Arrays larger than 64K.
  173.   o Runtime error recovery.
  174.  
  175. Turbo Professional 4.0 also comes with a dozen powerful demo programs,
  176. including a memory resident programmer's calculator, time management system,
  177. keyboard macro utility, and a source code generator for menu systems. With
  178. complete source code (over 30,000 lines of it) and a 450 page manual, Turbo
  179. Professional 4.0 is a bargain at $99.
  180.  
  181. Coming soon are an overlay manager for Turbo Pascal 4.0, and new versions of
  182. TDEBUG and TurboPower Utilities for the new compiler.
  183.  
  184. Call TurboPower Software at 408-438-8608 for more information.
  185.  
  186.