EXECUTE

  • Article

5/10/2007

This command creates a new process and a primary thread. The new process then runs the specified executable file in the security context of the specified credentials, such as user, domain, and password. As an option, it can load the user profile of the specified user.

Syntax

3, [ErrorMode], [RebootOK], [ExpandMode], [ApplicationName], [ExpandMode], 
[CommandLine], [WaitForCompletion], [Timeout], [ExpandMode],
[UserName], [ExpandMode], [Domain], [ExpandMode], [Password],[LogonFlags], 
[CreationFlags], [ExpandMode], [CurrentDirectory], [EnableUserInteraction], 
[ExpandMode], [Desktop_Name],[ExpandMode], [Title_String], [X_Loc], [Y_Loc], 
[X_Size], [Y_Size], [X_CountChars], [Y_CountChars], [FillAttributes], [Flags], 
[ShowWindows], [ExpandMode], [StdInStream], [ExpandMode], [StdOutStream], 
[ExpandMode], [StdErrStream], [ExpandMode], [Action], [ArraySize], [EnvironmentStrings]

Parameters

  • ErrorMode
    Optional. Specified as a decimal representation of a hexadecimal bitmask. Values must be specified in decimal format. The following table shows the possible values.

    Value Name Description

    0 (0xnnnn0000)

    DAERH_ABORT

    Default. The abort-on-error mode stops the command file from processing further.

    32768 (0xnnnn8000)

    DAERH_IGNORE

    The ignore-on-error mode continues by processing the next command when an error occurs.

    32769-33023 (0x000080xx where xx!=00 is the number of retries)

    DAERH_RETRY_WITHIGNORE

    The retry-on-error with ignore mode retries the offending command up to 255 times. If the number of retries exceeds the retry count, this mode continues processing the next command.

    1-255(0x00xx where xx!=0 is the number of retries from 1-255)

    DAERH_RETRY_WITHABORT

    The retry-on-error with abort mode retries the offending command up to 255 times. If the number of retries exceeds the retry count, the command file processing halts.

    65536 – 4294901760(0xFFFFnnnn where FFFF is the delay mask in seconds)

    DAERH_DELAYMASK

    The delay error mode value is added to either the DAERH_RETRY_WITHIGNORE or the DAERH_RETRY_WITHABORT value to cause a delay between retries. This value is in seconds and has a range between 1 and 65535.

    Note

    Parsing errors, especially the passing of not valid command parameters, generates an error in DAERH_ABORT error mode. With logging enabled, an appropriate error message is output to the log file.

  • RebootOK
    Optional. Specifies whether this command can cause a system reboot. The following table shows the possible values.

    Value Name Description

    0

    DANO

    Default. Cannot cause a system reboot.

    1

    DAYES

    Can cause a system reboot.

  • ExpandMode
    Optional. Specifies if the string that follows it is an environment variable that should be expanded. Can occur multiple times with this command. The following table shows the possible values.

    Value Description

    0

    Default. Does not expand the string.

    1

    Device Update Agent expands the string on the embedded device.

    2

    Device Update Agent script compiler expands the string on the development workstation.

  • ApplicationName
    Optional. Pointer to a null-terminated string that specifies the module to execute. The specified module can be a Windows-based application.

    The string can specify the full path and file name of the module to execute or it can specify a partial name. In the case of a partial name, it uses the current drive and current directory to complete the specification. It does not use the search path. If the file name does not contain an extension, .exe is assumed. Therefore, if the file name extension is .com, this parameter must include the .com extension.

  • CommandLine
    Optional. String that represents any command-line arguments to be passed to the executable file. Include the module name as the first token.

  • WaitForCompletion
    Optional. Specifies if the Device Update Agent should wait for the completion of the command being executed. The following table shows the possible values.

    Value Name Description

    0

    DANO

    Indicates that the Device Update Agent should not wait for the completion of the command being executed.

    1

    DAYES

    Indicates that the Device Update Agent should wait for the completion of the command being executed.

    2

    DASPECIAL

    Indicates that the Device Update Agent waits until the process that was started is waiting for user input.

  • Timeout
    Optional. Specifies, in milliseconds, how long the Device Update Agent should wait for a command to complete. The timeout value is used only if WaitForCompletion is DAYES or DASPECIAL.

    This parameter can have a value of 0 thru 4,294,967,295, with a default of 0. It specifies the time, in milliseconds. A value of 4,294,967,295 causes an infinite delay.

  • UserName
    Required. String that specifies the name of the user account to use when logging on. If you use the format user@DNS_domain_name, the Domain parameter should be NULL.

    The user account must have Log On Locally permission on the local computer. This permission is not granted to all users on workstations and servers, but only to administrators on domain controllers.

  • Domain
    Optional. String that specifies the name of the domain or server whose account database contains the user name account. Default is NULL.
  • Password
    Required. String that specifies the password for the user name account.

  • LogonFlags
    Optional. Specifies the logon option. The following table shows the possible values.

    Value Name Description

    1

    DALOGONWITHPROFILE

    Allows a logon with a profile.

    2

    DALOGONNETCREDENTIALSONLY

    Default. Allows a logon with only network credentials.
  • CreationFlags
    Optional. Defines how a process is created. For more information, see Creation Flags.
  • CurrentDirectory
    Optional. Specifies the path to the new current directory. This parameter can be a relative path or a fully qualified path. Default is NULL.

  • EnableUserInteraction
    Optional. Enabled users to interact with the process.

    Value Name

    0

    DANO

    1

    DAYES
  • Desktop_Name
    Optional. Part of the STARTUPINFO struct that is used to create a new process. Pointer to a null-terminated string that specifies either the name of the desktop, or the name of both the desktop and window station for this process. A backslash in the string indicates that the string includes both the desktop and window station names.
  • Title_String
    Optional. Part of the STARTUPINFO struct that is used to create a new process. For console processes, this is the title displayed in the title bar if a new console window is created. If NULL, the name of the executable file is used as the window title instead. This parameter must be NULL for GUI or console processes that do not create a new console window.

  • X_Loc
    Optional. Part of the STARTUPINFO struct that is used to create a new process. If Flags specifies STARTF_USEPOSITION, this member is the x offset of the upper left corner of a window if a new window is created, in pixels. Otherwise, this member is ignored.

    The offset is from the upper left corner of the screen. For GUI processes, the specified position is used the first time the new process calls CreateWindow to create an overlapped window if the x parameter of CreateWindow is CW_USEDEFAULT.

  • X_Size
    Optional. Part of the STARTUPINFO struct that is used to create a new process. If Flags specifies STARTF_USESIZE, this member is the width of the window if a new window is created, in pixels. Otherwise, this member is ignored.

    For GUI processes, this is used only the first time the new process calls CreateWindow to create an overlapped window if the nWidth parameter of CreateWindow is CW_USEDEFAULT.

  • Y_Size
    Optional. Part of the STARTUPINFO struct that is used to create a new process. If Flags specifies STARTF_USESIZE, this member is the height of the window if a new window is created, in pixels. Otherwise, this member is ignored.

    For GUI processes, this is used only the first time the new process calls CreateWindow to create an overlapped window if the nHeight parameter of CreateWindow is CW_USEDEFAULT.

  • X_CountChars
    Optional. Part of the STARTUPINFO struct that is used to create a new process. If Flags specifies STARTF_USECOUNTCHARS, and if a new console window is created in a console process, this member specifies the screen buffer width, in character columns. Otherwise, this member is ignored.
  • Y_CountChars
    Optional. Part of the STARTUPINFO struct that is used to create a new process. If Flags specifies STARTF_USECOUNTCHARS, and if a new console window is created in a console process, this member specifies the screen buffer width, in character columns. Otherwise, this member is ignored.

  • FillAttributes
    Optional. Part of the STARTUPINFO struct that is used to create a new process. If Flags specifies STARTF_USEFILLATTRIBUTE, this member is the initial text and background colors if a new console window is created in a console application. Otherwise, this member is ignored.

    This value can be any combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces red text on a white background:

    FOREGROUND_RED| BACKGROUND_RED| BACKGROUND_GREEN| BACKGROUND_BLUE

  • Flags
    Optional. Part of the STARTUPINFO struct that is used to create a new process. Bit field that determines whether certain STARTUPINFO members are used when the process creates a window. This member can be one or more of the following values.

    Value Description

    STARTF_FORCEONFEEDBACK

    Indicates that the cursor is in feedback mode for two seconds after CreateProcess is called. The Working in Background cursor is displayed (see the Pointers tab in the Mouse control panel utility).

    If during those two seconds the process makes the first GUI call, the system gives five more seconds to the process. If during those five seconds the process shows a window, the system gives five more seconds to the process to finish drawing the window.

    The system turns the feedback cursor off after the first call to GetMessage, regardless of whether the process is drawing.

    STARTF_FORCEOFFFEEDBACK

    Indicates that the feedback cursor is forced off while the process is starting. The Normal Select cursor is displayed.

    STARTF_RUNFULLSCREEN

    Indicates that the process should be run in full-screen mode, rather than in windowed mode.

    This flag is only valid for console applications running on an x86 computer.

    STARTF_USECOUNTCHARS

    If this value is not specified, the dwXCountChars and dwYCountChars members are ignored.

    STARTF_USEFILLATTRIBUTE

    If this value is not specified, the dwFillAttribute member is ignored.

    STARTF_USEPOSITION

    If this value is not specified, the dwX and dwY members are ignored.

    STARTF_USESHOWWINDOW

    If this value is not specified, the wShowWindow member is ignored.

    STARTF_USESIZE

    If this value is not specified, the dwXSize and dwYSize members are ignored.

    STARTF_USESTDHANDLES

    Sets the standard input, standard output, and standard error handles for the process to the handles specified in the hStdInput, hStdOutput, and hStdError members of the STARTUPINFO structure. For this to work properly, the handles must be inheritable and the CreateProcess function's bInheritHandles parameter must be set to TRUE. For more information, see Handle Inheritance.

    If this value is not specified, the hStdInput, hStdOutput, and hStdError members of the STARTUPINFO structure are ignored.

  • ShowWindows
    Optional. Part of the STARTUPINFO struct that is used to create a new process. If Flags specifies STARTF_USESHOWWINDOW, this member can be any of the SW_ constants defined in Winuser.h. Otherwise, this member is ignored.

    For GUI processes, wShowWindow specifies the default value the first time ShowWindow is called. The nCmdShow parameter of ShowWindow is ignored. In subsequent calls to ShowWindow, the wShowWindow member is used if the nCmdShow parameter of ShowWindow is set to SW_SHOWDEFAULT

  • StdInStream
    Optional. Part of the STARTUPINFO struct that is used to create a new process. If Flags specifies STARTF_USESHOWWINDOW, this member can be any of the SW_ constants defined in Winuser.h. Otherwise, this member is ignored.

    For GUI processes, wShowWindow specifies the default value the first time ShowWindow is called. The nCmdShow parameter of ShowWindow is ignored. In subsequent calls to ShowWindow, the wShowWindow member is used if the nCmdShow parameter of ShowWindow is set to SW_SHOWDEFAULT

  • StdOutStream
    Optional. Part of the STARTUPINFO struct that is used to create a new process. If Flags specifies STARTF_USESTDHANDLES, this member is a handle to be used as the standard output handle for the process. Otherwise, this member is ignored.

  • Action
    Optional.

    • 0 = Replaces the current environment variable with the new value.
    • 1 = Adds the current environment variable value to the existing variable.

    For more information, see Environment Block.

  • ArraySize
    Optional. Specifies the number of environment strings. . For more information, see Environment Block.
  • Environment Strings
    Optional. Lists comma delimited environment strings. The number of strings are specified by ArraySize. For more information, see Environment Block.

Remarks

The RebootOK parameter indicates to the Device Update Agent that the command being executed can cause the system to reboot. By setting RebootOK to the DAYES value, the Device Update Agent expects a possible reboot and continues processing commands even if a reboot occurs. If the RebootOK parameter is set to the DANO value, the agent does not expect a reboot and stops processing commands if a reboot occurs because it was executing the current command.

For more information about the EXECUTE command and command parameters, see the CreateProcessWithLogonW function in the Microsoft Windows SDK documentation at this Microsoft Web site.

Example

The following example shows typical use.

//
// Execute: Execute cmd.exe.
//
EXECUTE,DAERH_ABORT,DANO,1,%windir%\System32\cmd.exe,1,%windir%\system32\cmd.exe /c c:\DUA-Test\simplescript.bat DUAtest.DUP NOTE,DAYES,,0,Administrator,,,0,password,,,,c:\DUA-Test\keywords\,1,,WinSta0\Default,,,,,,,,,,,,,,,,,0,0,1,2,srcPATH=C:\src,testPATH=C:\test

See Also

Concepts

DUA Script Command Reference