The OS/2 API Project

DosExecPgm

PCHAR pchProcName (output)

This is the address of the buffer which contains the name of the process that is responsible if the DosExecPgm failure is returned. For instance, if the parent process tries to running an program which doesn't exist, the inexistent file name will be put into this buffer.

LONG lProcName (input)

This is the length, in bytes, of the buffer pchProcName

ULONG ulExecFlag (input)

This is the flag which will lead the child process. There are the possible values:

0	EXEC_SYNC	The execution will be synchronous to the parent process. The termination code and result code are stored in the RESULTCODES structure of prcRes.
1	EXEC_ASYNC	The execution will be asynchronous to the parent process. When the child process execution is over, its result code will be lost. The PID is stored in the codeTerminate field of the RESULTCODES of prcRes.
2	EXEC_ASYNCRESULT	The execution will be asynchronous to the parent process. When the child process execution is over, its result code will be saved and will be retrieved by the DosWaitChild function. The PID is stored in the codeTerminate field of the RESULTCODES structure of prcRes.
3	EXEC_TRACE	Like EXEC_ASYNCRESULT but for debugging purposes. Only the child process will be concerned by the debugging session.
4	EXEC_BACKGROUND	The execution will be asynchronous in background. It is a orphan process and doesn't depend of the parent process termination. A such program shouldn't use any VIO, KDB or MOU functions other than VioPopups.
5	EXEC_LOAD	The process is loaded and is ready to execute, but isn't executed until the session manager dispatches the threads belonging to the process.
6	EXEC_ASYNCRESULTDB	Like EXEC_ASYNCRESULT, but for debbuging purposes. The child process and its descendants will be concerned by the debugging session.

Warning : unless using EXEC_SYNC and EXEC_ASYNC, result codes should be retrieved with DosWaitChild in order to avoid wasting memory, even if the result codes won't be used later.

PSZ pszArg (input)

This is the address of the argument string passed to the process. Example of a such argument string:
"UNZIP\0-l MYARCHIVE.ZIP *.BMP\0"
By default, the file name is searched in the default directory and through the PATH variable. If the program name isn't present into the PATH variable, the comprehensive access path must be present.
There are always a '\0' between the program name and the parameters. Moreover, a second '\0' must also be placed at the end of the argument string.

PSZ pszEnv (input)

This is the address of the environment string passed to the process. When a NULL value is passed into pszEnv, the child process will inherit the environment of its parent.

PSZ pszRes (output)

This is a pointer to the RESULTCODES structure.

PSZ pszName (input)

This is the address of the string which contains the file name of the child process with its extension which must be present.

APIRET rc

The following values can be returned

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
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

DO NOT launch a synchronous PM child process from a single-threaded PM process! It will choke the system messaging queue and you will have to do Ctrl-Esc to kill the process. I don't know if this problem will also appear from a multi-threaded PM process.

Authors

Additions

Last modified August 11/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com