dos12.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
DosExecPgm (1.2)
Function Group  Overview                          Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSPROCESS
 
USHORT DosExecPgm(pchFailName, cbFailName, fExecFlags, pszArgs, pszEnv,
    prescResults, pszPgmName)
PCHAR pchFailName;            /* pointer to buffer for failed filename */
SHORT cbFailName;             /* size of failed filename buffer        */
USHORT fExecFlags;            /* synchronous/trace flags               */
PSZ pszArgs;                  /* pointer to argument strings           */
PSZ pszEnv;                   /* pointer to environment strings        */
PRESULTCODES prescResults;    /* pointer to structure for result codes */
PSZ pszPgmName;               /* pointer to name of program to execute */
 
The DosExecPgm function loads and starts a child process.
 
The DosExecPgm function is a family API function.
 
Parameter     Description
────────────────────────────────────────────────────────────────────────────
 
pchFailName   Points to the buffer that receives the name of the object
              (such as a dynamic-link module). The DosExecPgm function
              copies a name to this buffer if it cannot load and start the
              specified program.
 
cbFailName    Specifies the length (in bytes) of the buffer pointed to by
              the pchFailName parameter.
 
fExecFlags    Specifies how a given program should be run. This parameter
              can be one of the following values:
 
              Value             Meaning
              ──────────────────────────────────────────────────────────────
              EXEC_ASYNC        Execute asynchronously to the parent
                                process. The DosExecPgm function copies the
                                process identifier of the child process to
                                the codeTerminate field of the structure
                                pointed to by the prescResults parameter.
 
              EXEC_ASYNCRESULT  Execute asynchronously to the parent
                                process. Before returning, the DosExecPgm
                                function copies the process identifier of
                                the child process to the codeTerminate field
                                of the structure pointed to by the
                                prescResults parameter. When the child
                                process ends, the system saves the
                                termination and result codes in memory it
                                reserves for these codes. This memory
                                remains allocated until the parent process
                                calls the DosCwait function to retrieve the
                                information.
 
              EXEC_SYNC         Execute synchronously to the parent process.
                                When the child process ends, the DosExecPgm
                                function copies its termination and result
                                codes to the structure pointed to by the
                                prescResults parameter.
 
              EXEC_BACKGROUND   Execute asynchronously to the parent process
                                and detach from the screen group of the
                                parent process. The detached process
                                executes in the background. If a process
                                terminates the parent process──for example,
                                by using the DosKillProcess function──the
                                child process continues to run. The child
                                process should not require screen output
                                (other than through the VioPopUp function).
                                The child process also should not call Vio,
                                Kbd, or Mou functions.
 
              EXEC_TRACE        Execute under conditions for tracing. The
                                parent process debugs the child process.
 
pszArgs       Points to a set of null-terminated argument strings that
              represent the program's command parameters. The argument
              strings are copied to the process's environment segment. The
              string can have any format but must end with two null
              characters. A typical format is the program name, a null
              character, the program parameters (separated by spaces), and
              two null characters.
 
              If this parameter is zero, no argument strings are passed to
              the child process.
 
pszEnv        Points to a set of null-terminated environment strings that
              represent environment variables and their current values. The
              environment strings are copied to the process's environment
              segment. These strings represent environment variables and
              their current values. An environment string has the following
              form:
 
                   variable=value
 
              Two or more strings can be concatenated to pass multiple
              environment strings to the child process. The last environment
              string must end with two null characters.
 
              If this parameter is zero, the child process inherits the
              unchanged environment of the parent process.
 
prescResults  Points to the RESULTCODES structure that receives the
              termination and result codes of the child process.
 
pszPgmName    Points to a null-terminated string that specifies the process
              to load and start. The string must be a valid MS OS/2 filename
              and include the filename extension. The string must specify an
              executable file.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_ACCESS_DENIED
     ERROR_AUTODATASEG_EXCEEDS_64k
     ERROR_BAD_ENVIRONMENT
     ERROR_BAD_FORMAT
     ERROR_DRIVE_LOCKED
     ERROR_DYNLINK_FROM_INVALID_RING
     ERROR_EXE_MARKED_INVALID
     ERROR_FILE_NOT_FOUND
     ERROR_INTERRUPT
     ERROR_INVALID_DATA
     ERROR_INVALID_EXE_SIGNATURE
     ERROR_INVALID_FUNCTION
     ERROR_INVALID_MINALLOCSIZE
     ERROR_INVALID_MODULETYPE
     ERROR_INVALID_ORDINAL
     ERROR_INVALID_SEGDPL
     ERROR_INVALID_SEGMENT_NUMBER
     ERROR_INVALID_STACKSEG
     ERROR_INVALID_STARTING_CODESEG
     ERROR_ITERATED_DATA_EXCEEDS_64K
     ERROR_LOCK_VIOLATION
     ERROR_NO_PROC_SLOTS
     ERROR_NOT_DOS_DISK
     ERROR_NOT_ENOUGH_MEMORY
     ERROR_PATH_NOT_FOUND
     ERROR_PROC_NOT_FOUND
     ERROR_RELOC_CHAIN_XEEDS_SEGLIM
     ERROR_SHARING_BUFFER_EXCEEDED
     ERROR_SHARING_VIOLATION
     ERROR_TOO_MANY_OPEN_FILES
 
Comments
 
If the filename is a complete path name (a drive name, path, and filename),
the DosExecPgm function loads the program from the specified location. If
only a filename is given and that filename is not found in the current
directory, the DosExecPgm function searches each directory specified in the
parent process's PATH environment variable for the given file.
 
The child process receives a discrete address space──that is, it receives
its own local descriptor table. This means that the parent process and the
child process cannot access each other's data. To pass data between
processes, the parent process typically opens a pipe by using the
DosMakePipe function before starting the child process, then lets the child
process access one end of the pipe.
 
The environment segment of the child process consists of the environment
strings (at offset zero), the program filename, and the argument strings.
The system passes the offset to the argument strings in the bx register and
the environment segment's selector in the ax register. These values can also
be retrieved by using the DosGetEnv function.
 
When the child process starts, it inherits all pipe handles and all open
file handles from the parent process. (File handles that are opened with the
fsOpenMode parameter of the DosOpen function set to OPEN_FLAGS_NOINHERIT are
not inherited by the child process──for more information, see the DosOpen
function.) The child process can use these handles immediately, without
opening or preparing them in any way. This gives the parent process control
over the files associated with the standard input, output, and error file
handles. For example, the parent process can redirect the standard output
from the screen to a file by opening the file and duplicating its handle as
the standard output handle (0x0001). If the child process then writes to the
standard output, the data goes to the file, not to the screen.
 
Restrictions
 
In real mode, the following restrictions apply to the DosExecPgm function:
 
♦  The only value allowed for the fExecFlags parameter is EXEC_SYNC.
 
♦  The buffer pointed to by the pchFailName parameter is filled with blanks,
   even if the function fails.
 
♦  The codeResult field of the RESULTCODES structure receives the exit code
   from either the DosExit function or the MS-DOS int 21h, 4cH system call,
   whichever is used to terminate the program.
 
Example
 
This example calls the DosExecPgm function to execute the program test.exe.
The program executes as a child process asynchronously with the parent
program.
 
RESULTCODES resc;
UCHAR szFailName[CCHMAXPATH];
 
UCHAR szCommandLine[] = { "test\0-option1 -option2\0" };
 
DosExecPgm(szFailName,      /* object-name buffer  */
    sizeof(szFailName),     /* length of buffer    */
    EXEC_SYNC,              /* sync flag           */
    szCommandLine,          /* argument string     */
    (PSZ) NULL,             /* environment string  */
    &resc,                  /* address of result   */
   "test.exe");             /* name of application */
 
See Also
 
DosCreateThread, DosCwait, DosExit, DosGetEnv, DosKillProcess, DosMakePipe,
DosOpen, VioPopUp, RESULTCODES