File.RunAs

number File.RunAs ( 

string  Filename,

string  Args = "",

string  WorkingFolder = "",

number  WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false,

string  UserName = "",

string  Password = "",

string  Domain = "",

number  LogonFlag = LOGON_NO_OPTION,

table   CreationOptions = nil,

table   ExtendedErrorInfo = nil )

Description

Runs an executable as a different user.

Parameters

Filename

(string) The path to the executable (.exe) file.

Args

(string) The command line arguments to pass to the executable.

WorkingFolder

(string) The working folder to set for the executable file.

Note: This sets the current directory for the operation to something other than the folder that the file is in. Normally, you can just leave it blank.

WindowMode

(number) The window mode to use:

CONSTANT

VALUE

DESCRIPTION

SW_SHOWNORMAL

1

Normal. (Default)

SW_MAXIMIZE

3

Maximized.

SW_MINIMIZE

6

Minimized.

SW_HIDE

0

Hide.

WaitForReturn

(boolean) Whether the application will wait until the executable has exited before continuing:

VALUE

DESCRIPTION

true

Wait.

false

Don't wait. (Default)

Note: This parameter must be set to true if you want to receive a process return code.

UserName

(string) The username that will be used to run the file. You must use the UPN format, (eg. user@DNS_domain_name) if you are logging onto a network domain and you don't specify a Domain parameter.

Password

(string) The password for the specified user name.

Domain

(string) The domain or server that contains an account database for the specified user. If you do not specify a domain, the UserName parameter must be in UPN format (eg. user@DNS_domain_name) if you are logging onto a network domain.

LogonFlag

(number) The logon flag to use. Choose from:

CONSTANT

VALUE

DESCRIPTION

LOGON_NO_OPTION

0

Do not logon with any profile. (Default)

LOGON_WITH_PROFILE

1

Log on, then load the user profile in the HKEY_USERS registry key. Loading the profile can be time-consuming, so it is best to use this value only if you must access the information in the HKEY_CURRENT_USER registry key.

LOGON_NETCREDENTIALS_ONLY

2

Log on, but use the specified credentials on the network only. This value can be used to create a process that uses a different set of credentials locally than it does remotely. This is useful in inter-domain scenarios where there is no trust relationship.

Note: The system does not validate the specified credentials. Therefore, the process can start, but it may not have access to network resources.

CreationOptions

(table) A table containing the creation options by name that control how the process is created. In the table, a value of true turns an option on, and a value of false turns the option off. If nil is passed, DefaultErrorMode, NewConsole and NewProcessGroup are set to true by default.

The following options can be set or unset in the table:

KEY

TYPE

DESCRIPTION

DefaultErrorMode

boolean

The new process does not inherit the error mode of the calling process. Instead, it gives the new process the current default error mode. You can pass false to inherit the error mode of the calling process, eg. {DefaultErrorMode=false}

NewConsole

boolean

Whether or not the new process has a new console, instead of inheriting the parent's console. eg. {NewConsole=false}

NewProcessGroup

boolean

Whether or not the new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. eg. {NewProcessGroup=false}

SeparateWOWVDM

boolean

Note: This flag is only valid starting a 16-bit Windows-based application.

Whether or not the new process runs in a private Virtual DOS Machine (VDM). By default, all 16-bit Windows-based applications run in a single, shared VDM. The advantage of running separately is that a crash only terminates the single VDM; any other programs running in distinct VDMs continue to function normally. Also, 16-bit Windows-based applications that run in separate VDMs have separate input queues, which means that if one application stops responding momentarily, applications in separate VDMs continue to receive input. eg. {SeparateWOWVDM=true}

Suspended

boolean

Whether or not the primary thread of the new process is created in a suspended state. eg.{Suspended=true}

UnicodeEnvironment

boolean

Whether or not the environment block uses Unicode characters. Otherwise, the environment block uses ANSI characters. eg. {UnicodeEnvironment=true}

ExtendedErrorInfo

(table) A table that will be filled with extended error information indexed by the following keys:

KEY

TYPE

DESCRIPTION

ErrorCode

number

The Windows error code.

ErrorMsg

string

The Windows error message.

Note: Since this parameter requires a table, you must first create the table before the action is called, for example, TableName={};

Returns

(number)  The process return code if the WaitForReturn parameter is set to true. If WaitForReturn is set to false 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: The termination status returned may be one of the following:

The exit value specified in the ExitProcess or TerminateProcess function.
The return value from the main or WinMain function of the process.
The exception value for an unhandled exception that caused the process to terminate.

See also:  Related Actions