en:docs:fapi:dosexecpgm

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
en:docs:fapi:dosexecpgm [2018/08/26 09:55] – prokusheven:docs:fapi:dosexecpgm [2021/10/16 14:05] (current) – prokushev
Line 1: Line 1:
-{{logos:os2.gif?35x35}} {{logos:dos.gif?35x35}}+{{page>en:templates:fapiint}} 
 + 
 ====== DosExecPgm ====== ====== DosExecPgm ======
  
 This call allows a program to request that another program execute as a child process. This call allows a program to request that another program execute as a child process.
  
-==Syntax==+===== Syntax =====
  
 +<code c>
 DosExecPgm (ObjNameBuf, ObjNameBufL, ExecFlags, ArgPointer, EnvPointer, ReturnCodes, PgmPointer) DosExecPgm (ObjNameBuf, ObjNameBufL, ExecFlags, ArgPointer, EnvPointer, ReturnCodes, PgmPointer)
 +</code>
 +
 +===== Parameters =====
  
-==Parameters== +  *ObjNameBuf ([[PCHAR]]) - output : Address of the name of the object that contributed to the failure of DosExecPgm is returned. 
-  *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. 
-  *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.
-  *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.     *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.     *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.
Line 22: Line 27:
 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. 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. +  *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:+  *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  variable=value
 The last ASCIIZ environment string must be followed by an additional byte of zeros. The last ASCIIZ environment string must be followed by an additional byte of zeros.
Line 51: Line 56:
 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]]. 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. +  *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.+  *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)     *0 - EXIT (normal)
     *1 - Hard error abort     *1 - Hard error abort
     *2 - Trap operation      *2 - Trap operation 
     *3 - Unintercepted DosKillProcess     *3 - Unintercepted DosKillProcess
-  *resultcode (USHORT) : Result code specified by the terminating synchronous process on its last DosExit call. +  *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.+  *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. 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.
  
-==Return Code== +===== Return Code ===== 
- rc (USHORT) - return+ 
 +rc ([[USHORT]]) - return 
 Return code descriptions are: Return code descriptions are:
 +
   *0 NO_ERROR   *0 NO_ERROR
   *1 ERROR_INVALID_FUNCTION   *1 ERROR_INVALID_FUNCTION
Line 97: Line 105:
   *201 ERROR_RELOC_CHAIN_XEEDS_SEGLIM   *201 ERROR_RELOC_CHAIN_XEEDS_SEGLIM
  
-==Remarks==+===== 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 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.
  
Line 108: Line 117:
 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. 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.+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. 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.+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.+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. 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===+==== 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: 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.    * 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. 
Line 129: Line 140:
 The second word contains the ResultCode specified by the terminating process on its DosExit call (or INT 21H AH=4CH call).  The second word contains the ResultCode specified by the terminating process on its DosExit call (or INT 21H AH=4CH call). 
  
-===Application Type Considerations===+ 
 +==== 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 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. +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. 
  
-==Bindings== +===== Bindings =====
-===C===+
  
 +==== C ====
 +<code c>
   typedef struct _RESULTCODES {  /* resc */   typedef struct _RESULTCODES {  /* resc */
        
Line 158: Line 173:
      
   USHORT       rc;            /* return code */   USHORT       rc;            /* return code */
 +</code>
  
- +==== MASM ==== 
-===MASM===+<code asm>
  
   RESULTCODES struc   RESULTCODES struc
Line 180: Line 196:
   PUSH@  ASCIIZ  PgmPointer    ;Program file path name string   PUSH@  ASCIIZ  PgmPointer    ;Program file path name string
   CALL   DosExecPgm   CALL   DosExecPgm
 +</code>
 Returns WORD Returns WORD
  
 +==== Example Code ====
  
-==Example Code== 
 This example starts up the program simple.exe and then waits for it to finish. Then the termination and return codes are printed. This example starts up the program simple.exe and then waits for it to finish. Then the termination and return codes are printed.
 +<code c>
    #define INCL_DOSPROCESS    #define INCL_DOSPROCESS
    #define START_PROGRAM "simple.exe"    #define START_PROGRAM "simple.exe"
Line 217: Line 233:
             RETURN_CODE);       /* Result code */             RETURN_CODE);       /* Result code */
   }   }
 +</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.  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. 
 +<code c>
  
   /* ---- process1.c ---- */   /* ---- process1.c ---- */
Line 278: Line 294:
            RETURN_CODE);               /* Result Code */            RETURN_CODE);               /* Result Code */
   }   }
 +</code>
  
 +===== Note =====
  
-== Note == +This text based on [[http://www.edm2.com/index.php?title=DosExecPgm_(FAPI)]]
- +
-This text based on [[www.edm2.com/index.php?title=DosExecPgm_(FAPI)]]+
  
 {{page>en:templates:fapi}} {{page>en:templates:fapi}}