Falcon 030 Power 2/F030_POWER2.iso/ST_STE/MAGS/ICTARI05.ARJ/ictari.05/MISC/PEXEC/PEXEC.TXT

Text File | 1993-06-21 | 6KB | 147 lines

PEXEC INFO
==========
Note:
    Child processes inherit default drive, default paths in each drive
and default devices on handles 0-5.
Counters on these structures are incremented when loaded, not when run,
and decremented when terminated. Thereforem repeated running may cause
problems as the counters on internal structures go negative.
This statement is valid on all versions of GEMDOS up to 0.19
Preferable to use mode 5, mode 6 to run multiple times.

Pexec() will fail if the parent has not Mshrink'ed itself to give the child
room to run. Remember to move the stack into the program memory before you
Mshrink it, otherwise your stack is not in your own memory!

MODES AVAILABLE
===============
0] LOAD AND GO
   Execute like a subroutine - returns a word from child or long GEMDOS error.
   Error=Pexec(0,Filename_ptr,cmdline_ptr,environment_ptr)
3] LOAD
   Load and return pointer to Basepage
   Basepage_ptr=Pexec(3,Filename_ptr,cmdline_ptr,environment_ptr)
4] GO
   Execute and return word from child or Long GEMDOS error.
   Keep in memory when run.
   Error=Pexec(4,0L,Basepage_ptr,0L)
   Mfree(Basepage_ptr->P_env)
   Mfree(Basepage_ptr)
5] MAKE BASEPAGE
   Allocate Environment and create Basepage with TPA of largest free block of
   memory. Return pointer to memory block (Basepage).
   Basepage_ptr=Pexec(5,0L,cmdline_ptr,environment_ptr)
   Load child into tpa after basepage
   Setup basepage text,data,bss start_addresses and lengths
6] GO then FREE
   Execute already loaded process, free it when finished - return as mode 0
   Only available on Gemdos v0.15 or higher.
   Error=Pexec(6,0L,Basepage_ptr,0L)
7] MAKE BASEPAGE WITH PRGFLAGS
   Same as Mode 5 but uses PRGFLAGS passed as parameter 2
   Basepage_ptr=Pexec(7,PRGFLAGS,cmdline_ptr,environment_ptr)

Filename=Null terminated string of full path\filename.ext
Cmdline=length_byte+string (less than 125 bytes)+Null
Environment=Null terminated strings of the form "VAR=value"
            terminated with double Null.
            If just Null, parent's environment string is used.

Mode 0 - Load & Go
------------------
1] Make sure File exists
2] Set up Environment,TPA and Basepage:
    Allocate Environment and Copy from Parent
    Allocate Largest Free block of memory to child process
    Set up Basepage - Lowtpa, Hitpa, Dta and Env pointers
    Copy file handles and default directory from parent
    Copy Command line into memory Block
3] Give ownership of Environment and Memory Block to child process
4] Load Child process Executable File and fill in rest of Basepage
5] Start Program:
    Set Parent Pointer in Memory Block to child process
    Set initial User Stack and put values in it
    Set child process as Global to Memory Block
    Run Child Process

Mode 3 - Load, don't go
-----------------------
Does steps 1, 2 and 4:
    Parent Process still owns all memory of child process

Mode 4 - Don't load, just go
----------------------------
Does step 5 only:
    Parent Process still owns memory of child process
    Environment and TPA are not freed when finished
    Memory Malloc'd by child IS freed

Mode 5 - Create Basepage
------------------------
Does Step 2 only

Mode 6 - Don't load, Just Go:
-----------------------------
Does Step 3 then Step 5:
    All Memory of child belongs to child

Mode 7 - Create Basepage
------------------------
Does Step 2 only:
    Accepts PRGFLAGS passed as second argument

NOTE:
    MODE 6 REQUIRES GEMDOS >=0.15
    MODE 7 REQUIRES GEMDOS >=0.19

RUNNING PEXEC(mode 0)
=====================
1] Put full file path and name into a string, ending with a NULL (0)
   e.g. "C:\TEST\FILE.EXT",0
2] Put command line into string_address+1
3] Put length of string into byte at string_address
4] Put all environment strings following each other,ending in a NULL
   e.g. "Path=c:\;c:\rsc",0,"Lib=c:\libs",0,0
5] Call Pexec(mode0,filename,cmdline,environment);

If Environment is 0.L, the parent's environment will be passed instead.

RETURN CODES
============
    When the child process exits, its return code is passed back to the parent
as a WORD. If pexec fails it will return a negative LONG.
Programs should only return negative values as indications of system failures
(e.g. not enough memory) and positive codes for their own messages.
Therefore, Exit all programs with Pterm(value) rather than Pterm0.

OTHER MODES
===========
Mode 3 followed by Mode 6 is the same as just mode 0

Mode 3 followed by Mode 4 is for load once, run many times
    This will only work if the child process either doesn't mshrink itself (not
recommended) or puts its new top of stack address into the basepage->hitpa.
Also, remember that text and data values will keep the values they had when
they were last run. Also the BSS does not get cleared (unless you do it!)
Also, if the parent changes current directory, it may not be passed so all file
operations should use full paths, not just filenames.

Mode 3 followed by Mode 5 followed by Mode 6
    Use Mode 3 to Load child Process
    Mshrink its TPA to Basepage+text+data+BSS
    For each Run:
    Use mode 5 to create Basepage,then fill it with fields of old one
    Execute this new basepage with mode 6
Mode 4 could be used with this method,but the tpa and environment must be
freed after execution.
Note that some programs may not like the idea that their basepage is not before
the text segment and that the program's memory is not after the BSS segment

Mode 5 (or 7) followed by mode 6
    Use mode 5 to create a basepage
    Fill its tpa with a RAM copy of the child process
    relocate it
    run it with mode 6
The best way to do it but needs mode 6 and uses more memory