DosExecPgm allows a program to request that another program execute as a child process.
The target program is located and loaded into storage (if necessary), a process is created for it and placed into execution. 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 for completion of the child process. Other threads in the requesting process may continue to run.
If asynchronous execution is indicated, DosExecPgm places the process ID of the started child process into the first doubleword of the pRes structure. If EXEC_ASYNCRESULT is specified for execFlag, the parent process can issue DosWaitChild (after DosExecPgm) to examine the result code returned when the child process ends. If the value of execFlag, is EXEC_ASYNC, the result code of the asynchronous child process is not returned to the parent process.
If synchronous execution is indicated, DosExecPgm places the termination code and result code into the pRes structure.
The new process is created with an address space separate and distinct from its parent; that is, a new linear address space is built for the process.
The new process inherits all file handles and pipes of its parent, although not necessarily with the same access rights:
A child process inherits file handles obtained by its parent process with DosOpen calls that indicated inheritance. The child process also inherits handles to pipes created by the parent process with DosCreatePipe. This means that the parent process has control over the meanings of standard input, output, and error. For example, the parent could write a series of records to a file, open the file as standard input, open a listing file as standard output, and then execute a sort program that takes its input from standard input and writes to standard output.
Because a child process can 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 file. For example, a parent process can create two pipes with DosCreatePipe requests. It can issue DosDupHandle to redefine the read handle of one pipe as standard input (0x0000), and the write handle of the other pipe as standard output (0x0001). 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 process writes to one pipe, and the parent process reads what the child process 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 that was started because the value of execFlag was EXEC_TRACE or EXEC_ASYNCRESULTDB is provided a trace flag facility. This facility and the trace buffers provided by DosDebug 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 DosExecPgm or DosStartSession.
A detached process is treated as an orphan of the parent process and runs in the background. Thus, it cannot make any VIO, KBD, or MOU calls, except from 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.
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 DosStopSession to start a Presentation Manager process from a non-Presentation Manager process.
The following are the register conventions for 32-bit programs:
Register