home *** CD-ROM | disk | FTP | other *** search
/ Falcon 030 Power 2 / F030_POWER2.iso / ST_STE / MAGS / ICTARI09.ARJ / ictari.09 / MISC / EXEC_INF / PEXEC.TXT < prev   
Text File  |  1994-04-14  |  6KB  |  158 lines
  1. PEXEC INFO
  2. ==========
  3. Note:
  4.     Child processes inherit default  drive,  default  paths in each drive
  5. and default devices on  handles  0-5.  Counters  on  these structures are
  6. incremented when loaded, not  when  run  and decremented when terminated.
  7. Therefore repeated running may cause problems as the counters on internal
  8. structures go negative. This statement is valid on all versions of GEMDOS
  9. up to 0.19 Preferable to use mode 5, mode 6 to run multiple times.
  10.  
  11. Pexec() will fail if the  parent  has  not  Mshrink'ed itself to give the
  12. child room to run. Remember to move   the  stack  into the program memory
  13. before you Mshrink it, otherwise your stack is not in your own memory!
  14.  
  15. MODES AVAILABLE
  16. ===============
  17.  
  18. 0] LOAD AND GO
  19.    Execute like a subroutine - returns  a  word from child or long GEMDOS
  20. error.
  21.    Error=Pexec(0,Filename_ptr,cmdline_ptr,environment_ptr)
  22.  
  23. 3] LOAD
  24.    Load and return pointer to Basepage
  25.    Basepage_ptr=Pexec(3,Filename_ptr,cmdline_ptr,environment_ptr)
  26.  
  27. 4] GO
  28.    Execute and return word from child or Long GEMDOS error.
  29.    Keep in memory when run.
  30.    Error=Pexec(4,0L,Basepage_ptr,0L)
  31.    Mfree(Basepage_ptr->P_env)
  32.    Mfree(Basepage_ptr)
  33.  
  34. 5] MAKE BASEPAGE
  35.    Allocate Environment and  create  Basepage  with  TPA  of largest free
  36.    block of memory. Return pointer to memory block (Basepage).
  37.    Basepage_ptr=Pexec(5,0L,cmdline_ptr,environment_ptr)
  38.    Load child into tpa after basepage
  39.    Setup basepage text,data,bss start_addresses and lengths
  40.  
  41. 6] GO then FREE
  42.    Execute already loaded process, free it  when finished- return as mode 0
  43.    Only available on Gemdos v0.15 or higher.
  44.    Error=Pexec(6,0L,Basepage_ptr,0L)
  45.  
  46. 7] MAKE BASEPAGE WITH PRGFLAGS
  47.    Same as Mode 5 but uses PRGFLAGS passed as parameter 2
  48.    Basepage_ptr=Pexec(7,PRGFLAGS,cmdline_ptr,environment_ptr)
  49.  
  50. Filename=Null terminated string of full path\filename.ext
  51. Cmdline=length_byte+string (less than 125 bytes)+Null
  52. Environment=Null terminated strings of the form "VAR=value"
  53.             terminated with double Null.
  54.             If just Null, parent's environment string is used.
  55.  
  56. Mode 0 - Load & Go
  57. ------------------
  58. 1] Make sure File exists
  59. 2] Set up Environment,TPA and Basepage:
  60.         Allocate Environment and Copy from Parent
  61.         Allocate Largest Free block of memory to child process
  62.         Set up Basepage - Lowtpa, Hitpa, Dta and Env pointers
  63.         Copy file handles and default directory from parent
  64.         Copy Command line into memory Block
  65. 3] Give ownership of Environment and Memory Block to child process
  66. 4] Load Child process Executable File and fill in rest of Basepage
  67. 5] Start Program:
  68.         Set Parent Pointer in Memory Block to child process
  69.         Set initial User Stack and put values in it
  70.         Set child process as Global to Memory Block
  71.         Run Child Process
  72.  
  73. Mode 3 - Load, don't go
  74. -----------------------
  75. Does steps 1, 2 and 4:
  76.         Parent Process still owns all memory of child process
  77.  
  78. Mode 4 - Don't load, just go
  79. ----------------------------
  80. Does step 5 only:
  81.         Parent Process still owns memory of child process
  82.         Environment and TPA are not freed when finished
  83.         Memory Malloc'd by child IS freed
  84.  
  85. Mode 5 - Create Basepage
  86. ------------------------
  87. Does Step 2 only
  88.  
  89. Mode 6 - Don't load, Just Go:
  90. -----------------------------
  91. Does Step 3 then Step 5:
  92.         All Memory of child belongs to child
  93.  
  94. Mode 7 - Create Basepage
  95. ------------------------
  96. Does Step 2 only:
  97.         Accepts PRGFLAGS passed as second argument
  98.  
  99. NOTE:
  100.         MODE 6 REQUIRES GEMDOS >=0.15
  101.         MODE 7 REQUIRES GEMDOS >=0.19
  102.  
  103. RUNNING PEXEC(mode 0)
  104. =====================
  105. 1] Put full file path and name into a string, ending with a NULL (0)
  106.    e.g. "C:\TEST\FILE.EXT",0
  107. 2] Put command line into string_address+1
  108. 3] Put length of string into byte at string_address
  109. 4] Put all environment strings following each other,ending in a NULL
  110.    e.g. "Path=c:\;c:\rsc",0,"Lib=c:\libs",0,0
  111. 5] Call Pexec(mode0,filename,cmdline,environment);
  112.  
  113. If Environment is 0.L, the parent's environment will be passed instead.
  114.  
  115. RETURN CODES
  116. ============
  117.     When the child process exits, its  return  code is passed back to the
  118. parent as a WORD. If pexec fails it will return a negative LONG.
  119. Programs should only  return  negative  values  as  indications of system
  120. failures (e.g. not  enough  memory)  and  positive  codes  for  their own
  121. messages.
  122. Therefore, Exit all programs with Pterm(value) rather than Pterm0.
  123.  
  124. OTHER MODES
  125. ===========
  126. Mode 3 followed by Mode 6 is the same as just mode 0
  127.  
  128. Mode 3 followed by Mode 4 is for load once, run many times
  129.     This will only  work  if  the  child  process  either doesn't mshrink
  130. itself (not recommended) or puts its   new   top  of  stack  address into
  131. the basepage-hitpa.
  132. Also, remember that text and data  values  will  keep the values they had
  133. when they were last run. Also the BSS does not get cleared (unless you do
  134. it!) Also, if the  parent  changes  current   directory,   it  may not be
  135. passed so all file operations should use full paths, not just filenames.
  136.  
  137. Mode 3 followed by Mode 5 followed by Mode 6
  138.     Use Mode 3 to Load child Process
  139.     Mshrink its TPA to Basepage+text+data+BSS
  140.     For each Run:
  141.     Use mode 5 to create Basepage,then fill it with fields of old one
  142.     Execute this new basepage with mode 6
  143.  
  144. Mode 4 could be used with this method,but the tpa and environment must be
  145. freed after execution.
  146. Note that some programs may not like  the idea that their basepage is not
  147. before the text segment and  that   the  program's  memory  is  not after
  148. the BSS segment
  149.  
  150. Mode 5 (or 7) followed by mode 6
  151.     Use mode 5 to create a basepage
  152.     Fill its tpa with a RAM copy of the child process
  153.     relocate it
  154.     run it with mode 6
  155.  
  156. The best way to do it but needs mode 6 and uses more memory
  157.  
  158.