DosExecPgm

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:
• 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.

  ---

  [Back: DosError]
  [Next: DosExit]