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

• A pointer to its environment segment
• The fully qualified path name 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 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.
  • 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

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.

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

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

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.

  typedef struct _RESULTCODES {  /* resc */
 
    USHORT codeTerminate;        /* Termination Code -or- Process ID */
    USHORT codeResult;           /* Exit Code */
 
  } RESULTCODES;
 
  #define INCL_DOSPROCESS
 
  USHORT  rc = DosExecPgm(ObjNameBuf, ObjNameBufL, ExecFlags, ArgPointer,
                               EnvPointer, ReturnCodes, PgmPointer);
 
  PCHAR        ObjNameBuf;    /* Address of object name buffer (returned) */
  SHORT        ObjNameBufL;   /* Length of object name buffer */
  USHORT       ExecFlags;     /* Execute asynchronously/trace */
  PSZ          ArgPointer;    /* Address of argument string */
  PSZ          EnvPointer;    /* Address of environment string */
  PRESULTCODES ReturnCodes;   /* Address of termination codes (returned) */
  PSZ          PgmPointer;    /* Address of program file name */
 
  USHORT       rc;            /* return code */

  RESULTCODES struc
 
  resc_codeTerminate dw  ? ;Termination Code -or- Process ID
  resc_codeResult    dw  ? ;Exit Code
 
  RESULTCODES ends
 
  EXTRN  DosExecPgm:FAR
  INCL_DOSPROCESS     EQU 1
 
  PUSH@  OTHER   ObjNameBuf    ;Object name buffer (returned)
  PUSH   WORD    ObjNameBufL   ;Length of object name buffer
  PUSH   WORD    ExecFlags     ;Execute asynchronously/trace
  PUSH@  ASCIIZ  ArgPointer    ;Address of argument string
  PUSH@  ASCIIZ  EnvPointer    ;Address of environment string
  PUSH@  DWORD   ReturnCodes   ;Termination codes (returned)
  PUSH@  ASCIIZ  PgmPointer    ;Program file path name string
  CALL   DosExecPgm

Returns WORD

This example starts up the program simple.exe and then waits for it to finish. Then the termination and return codes are printed.

   #define INCL_DOSPROCESS
   #define START_PROGRAM "simple.exe"
 
   CHAR        LoadError[100];
   PSZ         Args;
   PSZ         Envs;
   RESULTCODES ReturnCodes;
   USHORT      rc;
 
     if(!DosExecPgm(LoadError,           /* Object name buffer */
                    sizeof(LoadError),   /* Length of object name buffer */
                    EXEC_SYNC,           /* Asynchronous/Trace flags */
                    Args,                /* Argument string */
                    Envs,                /* Environment string */
                    &ReturnCodes,        /* Termination codes */
                    START_PROGRAM))      /* Program file name */
        printf("Termination Code %d  Return Code %d \n",
               ReturnCodes.codeTerminate,
               ReturnCodes.codeResult);
-- simple.exe --
 
  #define INCL_DOSPROCESS
  #define RETURN_CODE 0
 
  main()
  {
    printf("Hello!\n");
    DosExit(EXIT_PROCESS,       /* End thread/process */
            RETURN_CODE);       /* Result code */
  }

The following example demonstrates how to create a process, obtain process ID information, and kill a process. Process1 invokes process2 to run asynchronously. It obtains and prints some PID information, and then kills process2.

  /* ---- process1.c ---- */
  #define INCL_DOSPROCESS
  #include <os2.h>
  #define START_PROGRAM "process2.exe"   /* Program pointer */
 
  main()
  {
   CHAR          ObjFail [50];       /* Object name buffer */
   RESULTCODES   ReturnCodes;        /* */
   PIDINFO       PidInfo;
   PID           ParentID;           /* */
   USHORT        rc;
 
   printf("Process1 now running. \n");
 
   /** Start a child process. **/
   if(!(DosExecPgm(ObjFail,          /* Object name buffer */
                   sizeof(ObjFail),  /* Length of obj. name buffer */
                   EXEC_ASYNC,       /* Execution flag - asynchronous */
                   NULL,             /* No args. to pass to process2*/
                   NULL,             /* Process2 inherits process1's environment */
                   &ReturnCodes,     /* Ptr. to resultcodes struct. */
                   START_PROGRAM)))  /* Name of program file */
     printf("Process2 started. \n");
 
   /** Obtain Process ID information and print it **/
   if(!(rc=DosGetPID(&PidInfo)))       /* Process ID's (returned) */
     printf("DosGetPID: current process ID is %d; thread ID is %d; parent process ID is %d.\n",
             PidInfo.pid, PidInfo.tid, PidInfo.pidParent);
   if(!(rc=DosGetPPID(
            ReturnCodes.codeTerminate, /* Process whose parent is wanted */
            &ParentID)))               /* Address to put parent's PID */
     printf("Child process ID is %d; Parent process ID is %d.\n",
             ReturnCodes.codeTerminate, ParentID);
 
   /** Terminate process2 **/
   if(!(rc=DosKillProcess(DKP_PROCESSTREE,     /* Action code - kill process and descendants */
                 ReturnCodes.codeTerminate)))  /* PID of root of process tree */
     printf("Process2 terminated by process1.\n");
  }
 
 
  /* ---- process2.c ---- */
  #define INCL_DOSPROCESS
  #include <os2.h>
  #define SLEEPTIME   500L
  #define RETURN_CODE 0
 
  main()
  {
   printf("Process2 now running.\n");
 
   /* Sleep to allow process1 to kill it */
   DosSleep(SLEEPTIME);                /* Sleep interval */
   DosExit(EXIT_PROCESS,               /* Action Code */
           RETURN_CODE);               /* Result Code */
  }

This text based on http://www.edm2.com/index.php?title=DosExecPgm_(FAPI)