home *** CD-ROM | disk | FTP | other *** search
/ POINT Software Programming / PPROG1.ISO / pascal / exec33a / exec.h < prev    next >
Encoding:
C/C++ Source or Header  |  1991-11-21  |  16.4 KB  |  395 lines
  1. /*
  2.     --- Version 3.3 91-11-21 16:12 ---
  3.  
  4.    EXEC.H: EXEC function with memory swap - Main function header file.
  5.  
  6.    Public domain software by
  7.  
  8.         Thomas Wagner
  9.         Ferrari electronic GmbH
  10.         Beusselstrasse 27
  11.         D-1000 Berlin 21
  12.         Germany
  13. */
  14.  
  15.  
  16. extern int do_exec (char *xfn, char *pars, int spawn, unsigned needed,
  17.                           char **envp);
  18.  
  19. /*>e
  20.    The EXEC function.
  21.  
  22.       Parameters:
  23.  
  24.          xfn      is a string containing the name of the file
  25.                   to be executed. If the string is empty,
  26.                   the COMSPEC environment variable is used to
  27.                   load a copy of COMMAND.COM or its equivalent.
  28.                   If the filename does not include a path, the
  29.                   current PATH is searched after the default.
  30.                   If the filename does not include an extension,
  31.                   the path is scanned for a COM, EXE, or BAT file 
  32.                   in that order.
  33.  
  34.          pars     The program parameters.
  35.  
  36.          spawn    If 0, the function will terminate after the 
  37.                   EXECed program returns, the function will not return.
  38.  
  39.                   NOTE: If the program file is not found, the function 
  40.                         will always return with the appropriate error 
  41.                         code, even if 'spawn' is 0.
  42.  
  43.                   If non-0, the function will return after executing the
  44.                   program. If necessary (see the "needed" parameter),
  45.                   memory will be swapped out before executing the program.
  46.                   For swapping, spawn must contain a combination of the 
  47.                   following flags:
  48.  
  49.                      USE_EMS  (0x01)  - allow EMS swap
  50.                      USE_XMS  (0x02)  - allow XMS swap
  51.                      USE_FILE (0x04)  - allow File swap
  52.  
  53.                   The order of trying the different swap methods can be
  54.                   controlled with one of the flags
  55.  
  56.                      EMS_FIRST (0x00) - EMS, XMS, File (default)
  57.                      XMS_FIRST (0x10) - XMS, EMS, File
  58.  
  59.                   If swapping is to File, the attribute of the swap file
  60.                   can be set to "hidden", so users are not irritated by
  61.                   strange files appearing out of nowhere with the flag
  62.  
  63.                      HIDE_FILE (0x40)    - create swap file as hidden
  64.  
  65.                   and the behaviour on Network drives can be changed with
  66.  
  67.                      NO_PREALLOC (0x100) - don't preallocate
  68.                      CHECK_NET (0x200)   - don't preallocate if file on net.
  69.  
  70.                   This checking for Network is mainly to compensate for
  71.                   a strange slowdown on Novell networks when preallocating
  72.                   a file. You can either set NO_PREALLOC to avoid allocation
  73.                   in any case, or let the prep_swap routine decide whether
  74.                   to do preallocation or not depending on the file being
  75.                   on a network drive (this will only work with DOS 3.1 or 
  76.                   later).
  77.  
  78.          needed   The memory needed for the program in paragraphs (16 Bytes).
  79.                   If not enough memory is free, the program will 
  80.                   be swapped out. 
  81.                   Use 0 to never swap, 0xffff to always swap. 
  82.                   If 'spawn' is 0, this parameter is irrelevant.
  83.  
  84.          envp     The environment to be passed to the spawned
  85.                   program. If this parameter is NULL, a copy
  86.                   of the parent's environment is used (i.e.
  87.                   'putenv' calls have no effect). If non-NULL,
  88.                   envp must point to an array of pointers to
  89.                   strings, terminated by a NULL pointer (the
  90.                   standard variable 'environ' may be used).
  91.  
  92.       Return value:
  93.  
  94.          0x0000..00FF: The EXECed Program's return code
  95.  
  96.          0x0101:       Error preparing for swap: no space for swapping
  97.          0x0102:       Error preparing for swap: program too low in memory
  98.  
  99.          0x0200:       Program file not found
  100.          0x0201:       Program file: Invalid drive
  101.          0x0202:       Program file: Invalid path
  102.          0x0203:       Program file: Invalid name
  103.          0x0204:       Program file: Invalid drive letter
  104.          0x0205:       Program file: Path too long
  105.          0x0206:       Program file: Drive not ready
  106.          0x0207:       Batchfile/COMMAND: COMMAND.COM not found
  107.          0x0208:       Error allocating temporary buffer
  108.  
  109.          0x03xx:       DOS-error-code xx calling EXEC
  110.  
  111.          0x0400:       Error allocating environment buffer
  112.  
  113.          0x0500:       Swapping requested, but prep_swap has not 
  114.                        been called or returned an error.
  115.          0x0501:       MCBs don't match expected setup
  116.          0x0502:       Error while swapping out
  117.  
  118.          0x0600:       Redirection syntax error
  119.          0x06xx:       DOS error xx on redirection
  120. <*/
  121.  
  122. /*>d
  123.    Die EXEC Funktion.
  124.  
  125.       Parameter:
  126.  
  127.          xfn      ist ein String mit dem Namen der auszuführenden Datei.
  128.                   Ist der String leer, wird die COMSPEC Umgebungsvariable
  129.                   benutzt um COMMAND.COM oder das Equivalent zu laden.
  130.                   Ist kein Pfad angegeben, wird nach dem aktuellen Pfad
  131.                   der in der PATH Umgebungsvariablen angegebene Pfad
  132.                   durchsucht.
  133.                   Ist kein Dateityp angegeben, wird der Pfad nach
  134.                   einer COM oder EXE Datei (in dieser Reihenfolge) abgesucht.
  135.  
  136.          pars     Die Kommandozeile
  137.  
  138.          spawn    Wenn 0, wird der Programmlauf beendet wenn das
  139.                   aufgerufene Programm zurückkehrt, die Funktion kehrt
  140.                   nicht zurück.
  141.  
  142.                   HINWEIS: Wenn die auszuführende Datei nicht gefunden
  143.                         wird, kehrt die Funktion mit einem Fehlercode
  144.                         zurück, auch wenn der 'spawn' Parameter 0 ist.
  145.  
  146.                   Wenn nicht 0, kehrt die Funktion nach Ausführung des
  147.                   Programms zurück. Falls notwendig (siehe den Parameter
  148.                   "needed") wird der Programmspeicherbereich vor Aufruf 
  149.                   ausgelagert.
  150.                   Zur Auslagerung muß der Parameter eine Kombination der
  151.                   folgenden Flags enthalten:
  152.  
  153.                      USE_EMS  (0x01)  - Auslagerung auf EMS zulassen
  154.                      USE_XMS  (0x02)  - Auslagerung auf XMS zulassen
  155.                      USE_FILE (0x04)  - Auslagerung auf Datei zulassen
  156.  
  157.                   Die Reihenfolge der Versuche, auf die verschiedenen
  158.                   Medien auszulagern kann mit einem der folgenden
  159.                   Flags beeinflußt werden:
  160.  
  161.                      EMS_FIRST (0x00) - EMS, XMS, Datei (Standard)
  162.                      XMS_FIRST (0x10) - XMS, EMS, Datei
  163.  
  164.                   Wenn die Auslagerung auf Datei erfolgt, kann das
  165.                   Attribut dieser Datei auf "hidden" gesetzt werden,
  166.                   damit der Benutzer nicht durch unversehends auftauchende
  167.                   Dateien verwirrt wird:
  168.  
  169.                      HIDE_FILE (0x40) - Auslagerungsdatei "hidden" erzeugen
  170.  
  171.                   Außerdem kann das Verhalten auf Netzwerk-Laufwerken 
  172.                   beeinflußt werden mit
  173.  
  174.                      NO_PREALLOC (0x100) - nicht Präallozieren
  175.                      CHECK_NET (0x200)   - nicht Präallozieren wenn Netz.
  176.  
  177.                   Diese Prüfung auf Netzwerk ist hauptsächlich sinnvoll
  178.                   für Novell Netze, bei denen eine Präallozierung eine
  179.                   erhebliche Verzögerung bewirkt. Sie können entweder mit
  180.                   NO_PREALLOC eine Präallozierung in jedem Fall ausschließen,
  181.                   oder die Entscheidung mit CHECK_NET prep_swap überlassen.
  182.                   In diesem Fall wird nicht präalloziert wenn die Datei
  183.                   auf einem Netzwerk-Laufwerk liegt (funktioniert nur
  184.                   mit DOS Version 3.1 und späteren).
  185.  
  186.          needed   Der zur Ausführung des Programms benötigte Speicher
  187.                   in Paragraphen (16 Bytes). Wenn nicht ausreichend 
  188.                   freier Speicher vorhanden ist, wird der Programm-
  189.                   speicherbereich ausgelagert.
  190.                   Bei Angabe von 0 wird nie ausgelagert, bei Angabe
  191.                   von 0xffff wird immer ausgelagert.
  192.                   Ist der Parameter 'spawn' 0, hat 'needed' keine Bedeutung.
  193.  
  194.          envp     Die dem gerufenen Programm zu übergebenden 
  195.                   Umgebungsvariablen. Ist der Parameter NULL,
  196.                   wird eine Kopie der Vater-Umgebung benutzt,
  197.                   d.h. daß Aufrufe von "putenv" keinen Effekt haben.
  198.                   Wenn nicht NULL muß envp auf ein Array von Zeigern
  199.                   auf Strings zeigen, das durch einen NULL Zeiger
  200.                   abgeschlossen wird. Hierfür kann die Standardvariable 
  201.                   "environ" benutzt werden.
  202.  
  203.       Liefert:
  204.  
  205.          0x0000..00FF: Rückgabewert des aufgerufenen Programms
  206.  
  207.          0x0101:       Fehler bei Vorbereitung zum Auslagern
  208.                         kein Speicherplatz in XMS/EMS/Datei
  209.          0x0102:       Fehler bei Vorbereitung zum Auslagern
  210.                         der Programmcode ist zu nah am Beginn des
  211.                         Programms.
  212.  
  213.          0x0200:       Auszuführende Programmdatei nicht gefunden
  214.          0x0201:       Programmdatei: Ungültiges Laufwerk
  215.          0x0202:       Programmdatei: Ungültiger Pfad
  216.          0x0203:       Programmdatei: Ungültiger Dateiname
  217.          0x0204:       Programmdatei: Ungültiger Laufwerksbuchstabe
  218.          0x0205:       Programmdatei: Pfad zu lang
  219.          0x0206:       Programmdatei: Laufwerk nicht bereit
  220.          0x0207:       Batchfile/COMMAND: COMMAND.COM nicht gefunden
  221.          0x0208:       Fehler beim allozieren eines temporären Puffers
  222.  
  223.          0x03xx:       DOS-Fehler-Code xx bei Aufruf von EXEC
  224.  
  225.          0x0400:       Fehler beim allozieren der Umgebungsvariablenkopie
  226.  
  227.          0x0500:       Auslagerung angefordert, aber prep_swap wurde nicht
  228.                        aufgerufen oder lieferte einen Fehler
  229.          0x0501:       MCBs entsprechen nicht dem erwarteten Aufbau
  230.          0x0502:       Fehler beim Auslagern
  231.  
  232.          0x0600:       Redirection Syntaxfehler
  233.          0x06xx:       DOS-Fehler xx bei Redirection
  234. <*/
  235.  
  236. /*e Return codes (only upper byte significant) */
  237. /*d Fehlercodes (nur das obere Byte signifikant) */
  238.  
  239. #define RC_PREPERR   0x0100
  240. #define RC_NOFILE    0x0200
  241. #define RC_EXECERR   0x0300
  242. #define RC_ENVERR    0x0400
  243. #define RC_SWAPERR   0x0500
  244. #define RC_REDIRERR  0x0600
  245.  
  246. /*e Swap method and option flags */
  247. /*d Auslagerungsmethoden ond Optionen */
  248.  
  249. #define USE_EMS      0x01
  250. #define USE_XMS      0x02
  251. #define USE_FILE     0x04
  252. #define EMS_FIRST    0x00
  253. #define XMS_FIRST    0x10
  254. #define HIDE_FILE    0x40
  255. #define NO_PREALLOC  0x100
  256. #define CHECK_NET    0x200
  257.  
  258. #define USE_ALL      (USE_EMS | USE_XMS | USE_FILE)
  259.  
  260.  
  261. /*>e
  262.    The function pointed to by "spawn_check" will be called immediately 
  263.    before doing the actual swap/exec, provided that
  264.  
  265.       - the preparation code did not detect an error, and
  266.       - "spawn_check" is not NULL.
  267.  
  268.    The function definition is
  269.       int name (int cmdbat, int swapping, char *execfn, char *progpars)
  270.  
  271.    The parameters passed to this function are
  272.  
  273.       cmdbat      1: Normal EXE/COM file
  274.                   2: Executing BAT file via COMMAND.COM
  275.                   3: Executing COMMAND.COM (or equivalent)
  276.  
  277.       swapping    < 0: Exec, don't swap
  278.                     0: Spawn, don't swap
  279.                   > 0: Spawn, swap
  280.  
  281.       execfn      the file name to execute (complete with path)
  282.  
  283.       progpars    the program parameter string
  284.  
  285.    If the routine returns anything other than 0, the swap/exec will
  286.    not be executed, and do_exec will return with this code.
  287.  
  288.    You can use this function to output messages (for example, the
  289.    usual "enter EXIT to return" message when loading COMMAND.COM)
  290.    and to do clean-up and additional checking.
  291.  
  292.    CAUTION: If swapping is > 0, the routine may not modify the 
  293.    memory layout, i.e. it may not call any memory allocation or
  294.    deallocation routines.
  295.  
  296.    "spawn_check" is initialized to NULL.
  297. <*/
  298. /*>d
  299.    Die Funktion auf die "spawn_check" zeigt wird unmittelbar vor
  300.    Ausführung des Programmaufrufs aufgerufen, vorausgesetzt daß
  301.  
  302.       - bei der Vorbereitung kein Fehler auftrat, und
  303.       - "spawn_check" nicht NULL ist.
  304.  
  305.    Die Funktionsdefinition ist
  306.       int name (int cmdbat, int swapping, char *execfn, char *progpars)
  307.  
  308.    Die der Funktion übergebenen Parameter sind
  309.  
  310.       cmdbat      1: Normale EXE/COM Datei
  311.                   2: Ausführung BAT Datei über COMMAND.COM
  312.                   3: Ausführung COMMAND.COM (oder Equivalent)
  313.  
  314.       swapping    < 0: Exec, keine Auslagerung
  315.                     0: Spawn, keine Auslagerung
  316.                   > 0: Spawn, Auslagern
  317.  
  318.       execfn      Name und Pfad der auszuführenden Datei
  319.  
  320.       progpars    Programmparameter
  321.  
  322.    Wenn die Routine einen Wert verschieden von 0 liefert, wird der
  323.    Programmaufruf nicht durchgeführt, und do_exec kehrt mit diesem
  324.    Wert zurück.
  325.  
  326.    Sie können diese Funktion benutzen um Meldungen auszugeben
  327.    (zum Beispiel die übliche Meldung "Geben Sie EXIT ein um 
  328.    zurückzukehren" bei Laden von COMMAND.COM), und für sonstige
  329.    Prüfungen oder Aufräumarbeiten.
  330.  
  331.    ACHTUNG: Wenn swapping > 0 ist, darf die Funktion keinesfalls 
  332.    den Speicheraufbau verändern, d.h. es dürfen keine Speicher-
  333.    Allozierungs oder -Deallozierungsroutinen benutzt werden.
  334.  
  335.    "spawn_check" ist auf NULL initialisiert.
  336. <*/
  337.  
  338. typedef int (spawn_check_proc)(int cmdbat, int swapping, char *execfn, char *progpars);
  339. extern spawn_check_proc *spawn_check;
  340.  
  341. /*>e
  342.    The 'swap_prep' variable can be accessed from the spawn_check
  343.    call-back routine for additional information on the nature and
  344.    parameters of the swap. This variable will ONLY hold useful
  345.    information if the 'swapping' parameter to spawn_check is > 0.
  346.    The contents of this variable may not be changed.
  347.  
  348.    The 'swapmethod' field will contain one of the flags USE_FILE, 
  349.    USE_XMS, or USE_EMS.
  350.  
  351.    Caution: The module using this data structure must be compiled
  352.    with structure packing on byte boundaries on, i.e. with /Zp1 for
  353.    MSC, or -a- for Turbo/Borland.
  354. <*/
  355. /*>d
  356.    Die Variable 'swap_prep' kann von der spawn_check Routine
  357.    benutzt werden um zusätzliche Informationen über Art und Parameter
  358.    der Auslagerung zu erfahren. Diese Variable enthält NUR DANN 
  359.    sinnvolle Werte wenn der 'swapping' Parameter von spawn_check > 0 ist.
  360.    Der Inhalt dieser Variablen darf keinesfalls verändert werden.
  361.  
  362.    Das Feld 'swapmethod' enthält einen der Werte USE_FILE, 
  363.    USE_XMS, oder USE_EMS.
  364.  
  365.    Achtung: Ein Modul das diese Datenstruktur benutzen will muß
  366.    mit Struktur-Adjustierung auf Byte-Grenze kompiliert werden, d.h.
  367.    mit /Zp1 für MSC, oder -a- für Turbo/Borland.
  368. <*/
  369.  
  370. typedef struct {
  371.                long xmm;            /*e XMM entry address */
  372.                                     /*d Einsprungadresse XMM */
  373.                int first_mcb;       /*e Segment of first MCB */
  374.                                     /*d Segment des ersten MCB */
  375.                int psp_mcb;         /*e Segment of MCB of our PSP */
  376.                                     /*d Segment des MCB unseres PSP */
  377.                int env_mcb;         /*e MCB of Environment segment */
  378.                                     /*d MCB des Umgebungsvariablenblocks */
  379.                int noswap_mcb;      /*e MCB that may not be swapped */
  380.                                     /*d MCB der nicht Ausgelagert wird */
  381.                int ems_pageframe;   /*e EMS page frame address */
  382.                                     /*d EMS-Seiten-Adresse */
  383.                int handle;          /*e EMS/XMS/File handle */
  384.                                     /*d Handle für EMS/XMS/Datei */
  385.                int total_mcbs;      /*e Total number of MCBs */
  386.                                     /*d Gesamtzahl MCBs */
  387.                char swapmethod;     /*e Method for swapping */
  388.                                     /*d Auslagerungsmethode */
  389.                char swapfilename[81]; /*e Swap file name if swapping to file */
  390.                                       /*d Auslagerungsdateiname */
  391.                } prep_block;
  392.  
  393. extern prep_block swap_prep;
  394.  
  395.