DosExecPgm

Bindings:  C, MASM 

This call allows a program to request that another program execute as a 
child process. 

 DosExecPgm     (ObjNameBuf, ObjNameBufL, ExecFlags, ArgPointer, 
                EnvPointer, ReturnCodes, PgmPointer) 
 

 ObjNameBuf (PCHAR) - output 
    Address of the name of the object that contributed to the failure of 
    DosExecPgm is returned. 

 ObjNameBufL (SHORT) - input 
    Length, in bytes, of the buffer described by ObjNameBuf. 

 ExecFlags (USHORT) - input 
    Indicates how the program executes in relation to the requestor and 
    whether execution is under conditions for debugging. 

    Value     Definition 

    0         Execution is synchronous to the parent process.  The 
              termination code and result code are stored in the two-word 
              structure. 

    1         Execution is asynchronous to the parent process. When the 
              child process terminates, its result code is discarded. The 
              process ID is stored in the first word of the two-word 
              structure ReturnCodes. 

    2         Execution is asynchronous to the parent process. When the 
              child process terminates, its result code is saved for 
              examination by a DosCwait request. The process ID is stored 
              in the first word of the two-word structure ReturnCodes. 

    3         Execution is the same as if ExecFlags=2 is specified, plus 
              debugging conditions are present for the child process. 

    4         Execution is asynchronous to and detached from the parent 
              process session.  When the detached process is started, it 
              is not affected by the ending of the parent process. 

    5         The program is loaded into storage and made ready to 
              execute, but is not placed into execution until the session 
              manager dispatches the threads belonging to the process. 

    6         Execution is the same as if ExecFlag=2 is specified, with 
              the addition of debugging conditions being present for the 
              child process and any of its descendants. 

              Some memory is consumed for uncollected result codes. Issue 
              DosCwait to release this memory. If result codes are not 
              collected, then ExecFlags=0 or 1 should be used. 

 ArgPointer (PSZ) - input 
    Address of the ASCIIZ Argument strings passed to the program. These 
    strings represent command parameters, which are copied to the 
    environment segment of the new process. The convention used by CMD.EXE 
    is that the first of these strings is the program name (as entered 
    from the command prompt or found in a batch file), and the second 
    string consists of parameters to the program name. The second ASCIIZ 
    string is followed by an additional byte of zeros. A value of 0 for 
    the address of ArgPointer means that no arguments are to be passed. 

 EnvPointer(PSZ) - input 
    Address of the ASCIIZ environment strings passed to the program. These 
    strings represent environment variables and their current values. An 
    environment string has the following form: 

    variable=value
    

    The last ASCIIZ environment string must be followed by an additional 
    byte of zeros. 

    A value of 0 for the address of EnvPointer results in the new process 
    inheriting the environment of its parent process. 

    When the new process is given control, it receives: 

    o A pointer to its environment segment 
    o The fully qualified path name of the executable file 
    o A copy of the argument strings. 

      A coded example of this follows: 

      eo:   ASCIIZ string 1  ; environment string 1
            ASCIIZ string 2  ; environment string 2
      .
      .
      .
            ASCIIZ string n  ; environment string n
            Byte of 0
      .
      .
      .
      po:   ASCIIZ           ; string of filename
                             ; of program to run.
      .
      .
      .
      ao:   ASCIIZ           ; argument string 1
            ASCIIZ           ; argument string 2
            Byte of 0
      

      The beginning of the environment segment is "eo" and "ao" is the 
      offset of the first argument string in that segment. Register BX 
      contains "ao" on entry to the target program. The address to the 
      environment segment can also be obtained by issuing DosGetInfoSeg. 

 ReturnCodes (PRESULTCODES) - output 
    Address of the structure containing the process ID or termination code 
    and the result code indicating the reason for the child's termination. 
    This structure is also used by a DosCwait request, which waits for an 
    asynchronous child process to end. 

    termcodepid (USHORT) 
       For an asynchronous request, the process identifier of the child 
       process. For a synchronous request, the termination code furnished 
       by the system describes  why the child terminated. 

       Value     Definition 
       0         EXIT (normal) 
       1         Hard error abort 
       2         Trap operation 
       3         Unintercepted DosKillProcess 

    resultcode (USHORT) 
       Result code specified by the terminating synchronous process on its 
       last DosExit call. 

 PgmPointer (PSZ) - input 
    Address of the name of the file that contains the program to be 
    executed.  When the environment is passed to the target program, this 
    name is copied into "po" in the environment description shown above. 

    If the string appears to be a fully qualified path (it contains a ":" 
    in the second position - or it contains a "\" - or both), then the 
    file name must include the extension .COM or .EXE, and the program is 
    loaded from the indicated drive:directory. If the string is not a 
    fully qualified path, the current directory is searched.  If the file 
    name is not found in the current directory, each drive:directory 
    specification in the PATH defined in the current process' environment 
    is searched for this file. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    1         ERROR_INVALID_FUNCTION 
    2         ERROR_FILE_NOT_FOUND 
    3         ERROR_PATH_NOT_FOUND 
    4         ERROR_TOO_MANY_OPEN_FILES 
    5         ERROR_ACCESS_DENIED 
    8         ERROR_NOT_ENOUGH_MEMORY 
    10        ERROR_BAD_ENVIRONMENT 
    11        ERROR_BAD_FORMAT 
    13        ERROR_INVALID_DATA 
    26        ERROR_NOT_DOS_DISK 
    32        ERROR_SHARING_VIOLATION 
    33        ERROR_LOCK_VIOLATION 
    36        ERROR_SHARING_BUFFER_EXCEEDED 
    89        ERROR_NO_PROC_SLOTS 
    95        ERROR_INTERRUPT 
    108       ERROR_DRIVE_LOCKED 
    127       ERROR_PROC_NOT_FOUND 
    180       ERROR_INVALID_SEGMENT_NUMBER 
    182       ERROR_INVALID_ORDINAL 
    188       ERROR_INVALID_STARTING_CODESEG 
    189       ERROR_INVALID_STACKSEG 
    190       ERROR_INVALID_MODULETYPE 
    191       ERROR_INVALID_EXE_SIGNATURE 
    192       ERROR_EXE_MARKED_INVALID 
    194       ERROR_ITERATED_DATA_EXCEEDS_64k 
    195       ERROR_INVALID_MINALLOCSIZE 
    196       ERROR_DYNLINK_FROM_INVALID_RING 
    198       ERROR_INVALID_SEGDPL 
    199       ERROR_AUTODATASEG_EXCEEDS_64k 
    201       ERROR_RELOC_CHAIN_XEEDS_SEGLIM 
 
 Remarks 

 The target program is located and loaded into storage if necessary.  A 
 process is created and executed for the target program.  The new process 
 is created with an address space separate from its parent; that is, a new 
 Local Descriptor Table (LDT) is built for the process. 

 The execution of a child process can be synchronous or asynchronous to 
 the execution of its parent process. If synchronous execution is 
 indicated, the requesting thread waits pending completion of the child 
 process.  Other threads in the requesting process may continue to run. 

 If asynchronous execution is indicated, DosExecPgm returns with the 
 process ID of the started child process. Specifying ExecFlags=2 allows 
 the parent process to issue a DosCwait request after the DosExecPgm 
 request, so it can examine the result code returned when the child 
 process terminates. If ExecFlags=1 is specified, the result code of the 
 asynchronous child process is not returned to the parent process. 

 A child process inherits file handles obtained by its parent with DosOpen 
 calls that indicated inheritance .  The child process also inherits 
 handles to pipes created by the parent process with DosMakePipe. 

 Because a child process has the ability to inherit handles and a parent 
 process controls the meanings of handles for standard I/O, the parent can 
 duplicate inherited handles as handles for standard I/O. This permits the 
 parent process and the child process to coordinate I/O to a pipe or a 
 file. 

 For example, a parent process can create two pipes with DosMakePipe 
 requests.  It can issue DosDupHandle to redefine the read handle of one 
 pipe as standard input (0000H), and the write handle of the other pipe as 
 standard output (0001H).  The child process uses the standard I/O 
 handles, and the parent process uses the remaining read and write pipe 
 handles.  Thus, the child process reads what the parent writes to one 
 pipe, and the parent process reads what the child writes to the other 
 pipe. 

 When an inherited file handle is duplicated, the position of the file 
 pointer is always the same for both handles, regardless of which handle 
 repositions the file pointer. 

 An asynchronous process started with ExecFlags=3 or ExecFlags=6 is 
 provided a trace flag facility.  This facility and the Ptrace buffer 
 provided by DosPtrace enable a debugger to perform breakpoint debugging. 
  DosStartSession provides additional debugging capabilities that allow a 
 debugger to trace all processes associated with an application running in 
 a child session, regardless of whether the process is started with a 
 DosExecPgm or a DosStartSession request. 

 A detached process is treated as an orphan of the parent process and 
 executes in the background.  Thus, it cannot make any VIO, KBD, or MOU 
 calls, except within a video pop-up requested by VioPopUp. To test 
 whether a program is running detached, use the following method.  Issue a 
 video call, (for example, VioGetAnsi).  If the call is not issued within 
 a video pop-up and the process is detached, the video call returns error 
 code ERROR_VIO_DETACHED. 

 Note:  If the target program's entry point is in a segment that has IOPL 
        indicated, this causes a general protection fault and the process 
        is terminated. If any dynamic link module being used by the new 
        process has an initialization routine specified in a segment that 
        has IOPL indicated, general protection fault occurs and the 
        process is terminated. 

 
 Family API Considerations 

 Some options operate differently in DOS mode than in OS/2 mode. 
  Therefore, the following restrictions apply to DosExecPgm when coding in 
 DOS mode: 

 o ExecFlags must be set to zero.  This value is not related to the PID of 
   the program being executed. If ExecFlags <> 0, DosExecPgm returns the 
   error code ERROR_INVALID_DATA. 

 o The ObjNameBuf field is used to provide additional information in the 
   OS/2 mode environment as to why the DosExecPgm failed.  The information 
   is not relevant or available in DOS 2.X or DOS 3.X. Therefore, the 
   buffer is filled in with blanks. 

 o The ReturnCodes two-word structure is very similar to the OS/2 mode 
   environment. The first word is a termination code with the following 
   meanings: 

    Value     Definition 
    0         Exit (normal exit and termination by call INT 21H AH=31H) 
    1         Hard error abort 
    2         Not returned 
    3         Termination by Ctrl -Break. 

              The second word contains the ResultCode specified by the 
              terminating process on its DosExit call (or INT 21H AH=4CH 
              call). 
 
 Application Type Considerations 

 You may use DosExecPgm to start a process that is of the same type as the 
 starting process. Process types include Presentation Manager, 
 text-windowed, and full-screen. You may not use DosExecPgm to start a 
 process that is of a different type than the starting process. 

 You must use DosStartSession to start a new process from a process that 
 is of a different type. For example, use DosStartSession to start a 
 Presentation Manager process from a non-Presentation Manager process.