pObjname (PCHAR) - output

Address of the buffer in which the name of the object that contributed to the failure of DosExecPgm is returned.

cbObjname (LONG) - input

Length, in bytes, of the buffer described by pObjname.

execFlag (ULONG) - input

Flag indicating how the program runs in relation to the requester, and whether execution is under conditions for debugging.

The values of this field are shown in the following list:

• EXEC_SYNC Execution is synchronous to the parent process. The termination code and result code are stored in the RESULTCODES structure pointed to by pRes.

• EXEC_ASYNC
  Execution is asynchronous to the parent process. When the child process ends, its result code is discarded. The process ID is stored in the codeTerminate field of the RESULTCODES structure pointed to by pRes.

• EXEC_ASYNCRESULT
  Execution is asynchronous to the parent process. When the child process ends, its result code is saved for examination by a DosWaitChild request. The process ID is stored in the codeTerminate field of the RESULTCODES structure pointed to by pRes.

• EXEC_TRACE
  Execution is the same as if EXEC_ASYNCRESULT were specified for execFlag. Debugging conditions are present for the child process.

• EXEC_BACKGROUND
  Execution is asynchronous to and detached from the parent-process session. When the detached process starts, it is not affected by the ending of the parent process. The detached process is treated as an orphan of the parent process.

  A program executed with this option runs in the background, and should not require any input from the keyboard or output to the screen other than VioPopups. It should not issue any console I/O calls (VIO, KBD, or MOU functions).

• EXEC_LOAD
  The program is loaded into storage and made ready to execute, but is not executed until the session manager dispatches the threads belonging to the process.

• EXEC_ASYNCRESULTDB
  Execution is the same as if EXEC_ASYNCRESULT were specified for execFlag, with the addition of debugging conditions being present for the child process and any of its descendants. In this way, it is possible to debug even detached and synchronous processes.

  Some memory is consumed for uncollected result codes. Issue DosWaitChild to release this memory. If result codes are not collected, then EXEC_SYNC or EXEC_ASYNC should be used for execFlag.

pArg (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 the parameters for the program. The second ASCIIZ string is followed by an additional byte of zeros. A value of zero for the address of pArg means that no arguments are to be passed to the program.

pEnv (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 pEnv results in the new process' inheriting the environment of its parent process.

When the new process is given control, it receives:

• A pointer to its environment segment
  
• The fully qualified file specification of the executable file
  
• 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 file name
                       ; of program to run.
.
.
.
ao:   ASCIIZ           ; argument string 1
                       ; (name of program being started
                       ; for the case of CMD.EXE)
      ASCIIZ           ; argument string 2
                       ; (program parameters following
                       ; program name for the case of
                       ; CMD.EXE)
      Byte of 0

The beginning of the environment segment is "eo", and "ao" is the offset of the first argument string in that segment. The offset to the command line, "ao", is passed to the program on the stack at SS:[ESP+16].

The environment strings typically have the form: parameter = value

A value of zero for pEnv causes the newly created process to inherit the parent's environment unchanged.

pRes (PRESULTCODES) - output

Pointer to the RESULTCODES structure where the process ID, or the termination code and the result code indicating the reason for ending the child process is returned.

This structure also is used by a DosWaitChild request, which waits for an asynchronous child process to end.

pName (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 file specification (that is, it contains a ":" or a "\" in the second position), then the file name must include the extension, 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. Note that any extension (.XXX) is acceptable for the executable file being loaded.

ulrc (APIRET) - returns

Return Code.

DosExecPgm returns one of the following values:

• 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
  31
  ERROR_GEN_FAILURE
  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
  182
  ERROR_INVALID_ORDINAL
  190
  ERROR_INVALID_MODULETYPE
  191
  ERROR_INVALID_EXE_SIGNATURE
  192
  ERROR_EXE_MARKED_INVALID
  195
  ERROR_INVALID_MINALLOCSIZE
  196
  ERROR_DYNLINK_FROM_INVALID_RING
  For a full list of error codes, see Errors.