RtCreateProcess (iwin32x)

Creates and starts a new INtime process.

BOOLEAN RtCreateProcess(
    LPCTSTR lpApplicationName,
    LPTSTR lpCommandLine,
    LPSECURITY_ATTRIBUTES lpProcessAttributes,
    LPSECURITY_ATTRIBUTES lpThreadAttributes,
    BOOLEAN bInheritHandles,
    DWORD dwCreationFlags,
    LPVOID lpEnvironment,
    LPCTSTR lpCurrentDirectory,
    LPSTARTUPINFO lpStartupInfo,
    LPPROCESS_INFORMATION lpProcessInformation
);

Parameters

lpApplicationName

Pointer to a null-terminated string that specifies the program to execute.

The string can specify the full path and filename of the module to execute or it can specify a partial path and filename.

Note that if the filename has an extension (such as .rta) it must be specified.

lpCommandLine

Pointer to a null-terminated string that specifies the command line to execute.

lpProcessAttributes

Ignored. Set to NULL.

lpThreadAttributes

Ignored. Set to NULL.

bInheritHandles

Ignored.

dwCreationFlags

Set to 0 (zero), or:

PROC_XM: Causes the process to be created in XM mode.
PROC_NOTXM: Cause the process to be created in non-XM mode.

When neither PROC_XM nor PROC_NOTXM is specified, the mode defaults to that set in the executable file.

lpEnvironment

Ignored. Set to NULL

lpCurrentDirectory

Ignored. Set to NULL

lpStartupInfo

Ignored. Set to NULL

lpProcessInformation

Pointer to a _PROCESS_INFORMATION structure that receives identification information about the new process.

Note: the values returned in the hThread and dwThreadId fields of the _PROCESS_INFORMATION structure will be zero, since they cannot be used from a Windows application.

Remarks

If lpProcessInformation is not NULL, the HANDLE of the new process returns; it should be closed when no longer required. If the process being loaded is not an iwin32 process then this parameter should be NULL, or else the process will be loaded but the call will fail with a status of ERROR_INVALID_HANDLE.

The thread's initial stack size is described in the image header of the specified program's executable file.

The thread begins execution at the image's entry point.

The process is assigned a 32-bit process identifier. The identifier is valid until the process terminates. It can be used to identify the process, or specified in RtOpenProcess to open a handle to the process.

The initial thread in the process is also assigned a 32-bit thread identifier. The identifier is valid until the thread terminates and can be used to uniquely identify the thread within the system. These identifiers are returned in the _PROCESS_INFORMATION structure.

The created process remains in the system until all threads within the process terminate and all handles to the process and its threads close through calls to RtCloseHandle.

The handles for the process and the main thread must be closed through calls to CloseHandle. If these handles are not needed, close them immediately after the process is created.

Return Values

Non-zero value: Success.
FALSE: Failure. For extended error information, call the Windows' GetLastError function.

Requirements

Versions	Defined in	Include	Link to
INtime 3.0	intime/nt/include/iwin32x.h	iwin32x.h	iwin32x.lib

Notes

This function operates in the Windows portion of your application.
The iwin32 API also includes an RtCreateProcess function that operates in the real-time portion of your application.