<RunOnce> and Sub-elements (Optional)

2/16/2009

The <RunOnce> element of an unattended installation is used for management tasks. For example, it can be used to install additional device drivers, Windows updates, or to run .exe files to install additional software. Any specified <RunOnce> commands are executed during the First Boot Agent (FBA) before Windows Embedded POSReady 2009 starts for the first time.

The <RunOnce> element contains the <RunOnceCommand> element, which contains two other elements: <DisplayName> and <Description>. The following table describes these three elements.

Example:

A sample <RunOnce> element:

<RunOnce>
<!--This element specifies additional programs and commands to run during Setup.-->
   <RunOnceCommand FilePath="C:\sample1.vbs" Attributes="/a /f /e" Flags="1" ErrorControl="1" Reboot="True" Timeout="100">
      <DisplayName Value="Sample Application Setup" />
      <Description Value="This RunOnce Command installs the Sample Application" />
   </RunOnceCommand>
</RunOnce>

The &lt;RunOnceCommand&gt; Element

You cannot specify more than 1,024 <RunOnceCommand> elements.

Syntax:

<RunOnceCommand FilePath="File_Path_String" Attributes="Attributes_String" Flags="0|1" ErrorControl="0|1" Reboot="True|False" Timeout="Timeout_Integer"/>

File_Path_String can be a full local drive path or a UNC path and file name of the executable file to run. Batch files must be called by using cmd.exe /c (for example: FilePath="%11%\cmd.exe" Attributes="/c \\\\RemotePath\\batchfile.cmd").

Attributes_String is used to pass command-line arguments to the application.

Flags="0" indicates that the program should create the process and wait the number of seconds specified by the Timeout attribute for it to exit before continuing. Flags="1" indicates that the program should create the process and continue.

ErrorControl="0" indicates that the program should continue if an error is encountered. ErrorControl="1" indicates that the program should stop on an error.

Reboot="True" tells the program to complete the operation, restart, and then continue. Reboot="False" tells the program to continue without rebooting.

Timeout_Integer specifies the time, in seconds, that a program is able to execute before it is ended; 0 indicates an infinite number of seconds. This value is ignored if Flags is set to 1.

Be aware that the <RunOnceCommand> element can be used multiple times in a <RunOnce> element; for example:

<RunOnceCommand FilePath =“C:\samplel.vbs” Attributes=“/a /f /e” Flags=“1” ErrorControl=“l” Reboot=“True” Timeout=100” /

Examples

Installing a Windows Update

In this example, the update for Windows Embedded for Point of Service (KB945366) will be installed by a <RunOnce> command. The name of the downloaded update is WindowsXP-KB945366-x86-ENU.exe and the update is located on a computer named WEPOSSetup.

<RunOnceCommand FilePath = "\\WEPOSSetup\WindowsPatches\WindowsXP-KB945366-x86-ENU.exe" Attributes = "/quiet" Flags = "1" ErrorControl = "1" Reboot = "False" Timeout = “0”>
   <DisplayName Value = "Install an update for Windows Embedded for Point of Service (KB945366)" />
   <Description Value = "This RunOnce Command installs an update for Windows Embedded for Point of Service (KB945366)" />
</RunOnceCommand>

Installing an Application

In this example, Microsoft SQL Server 2005 Express will be installed. The name of the downloaded installation package is SQLExpr.exe. It is downloaded and unpackaged in the SQLE folder on a computer named POSReadySetup. The unpackaged installation package is called Setup.exe.

<RunOnceCommand FilePath = "\\POSReadySetup\POSReadyApps\SQLE\Setup.exe" Attributes = "/q" Flags = "1" ErrorControl = "1" Reboot = "False" Timeout = “0”>
   <DisplayName Value = "Install Microsoft SQL Server 2005 Express" />
   <Description Value = "This RunOnce Command installs Microsoft SQL Server 2005 Express" />
</RunOnceCommand>

Turning on DUA and Setting Properties

This is an example of turning on the Device Update Agent (DUA) service and modifying the settings. All these settings are in the registry and are set in the DUA.reg file. For more information about DUA registry settings, see this https://go.microsoft.com/fwlink/?LinkId=130049.

<RunOnceCommand FilePath = "regedit.exe" Attributes = "-s \\POSReadySetup\POSReadySettings\DUA.reg" Flags = "1" ErrorControl = "1" Reboot = "False" Timeout = “0”>
   <DisplayName Value = "Turns on the DUA Service and sets the appropriate properties." />
   <Description Value = "Turns on the DUA Service and sets the appropriate properties." />
</RunOnceCommand>

The DUA.reg file has the following contents:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\DUAgent]
"Start"=dword:00000002

[HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\DUAgent\Parameters]

[HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\DUAgent\Parameters\Config]
"RunOnStart"=dword:00000000
"PollInterval"=dword:00000000
"PollJitter"=dword:00000000
"PollToD"=hex:40,ff,ff,ff,20,ff,ff,ff,10,ff,ff,ff,08,ff,ff,ff,04,ff,ff,ff,02,\
 ff,ff,ff,01,ff,ff,ff

[HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\DUAgent\Parameters\Config\Sessions]

[HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\DUAgent\Parameters\Config\Sessions\0000]
"Type"=dword:00000000
"CmdFile"=hex(2):43,00,3a,00,5c,00,57,00,49,00,4e,00,44,00,4f,00,57,00,53,00,\
 5c,00,74,00,65,00,6d,00,70,00,00,00

Adding an Environment Variable

The following is an example of creating an environment variable:

<RunOnceCommand FilePath = "cmd.exe" Attributes = "set sample=POSReady" Flags = "1" ErrorControl = "1" Reboot = "False" Timeout = “0">
   <DisplayName Value = "Sets sample to POSReady." />
   <Description Value = "Creates an environment variable named sample and sets it to POSReady." />
</RunOnceCommand>

Adding a Hook for System-Integrator Scripts

This is an example of having a placeholder for scripts where a system integrator can add a script to complete the operating system configuration.

In the following example, the OEM creates a <RunOnce> command that the system integrator will use to run any needed applications or to specify configuration settings. The system integrator must create a batch file that is located in C:\Windows\AppSetup and called SystemIntegrator.bat.

<RunOnceCommand FilePath = "cmd.exe" Attributes = "/c C:\AppSetup\SystemIntegrator.bat -s \\POSReadySetup\POSReadySettings\WindowsShell.reg" Flags = "1" ErrorControl = "1" Reboot = "False" Timeout = “0”>
   <DisplayName Value = "Notepad Shell" />
   <Description Value = "Changes the Windows Shell to the Notepad Application." />
</RunOnceCommand>

Set an Application Other Than Explorer as the Shell

This is an example of changing the shell of Windows.

In the following example, the shell is set to Notepad, and Notepad opens the POSReady Setup log. All these settings are in the registry and are set in the WindowsShell.reg file.

<RunOnceCommand FilePath = "regedit.exe" Attributes = "-s \\POSReadySetup\POSReadySettings\WindowsShell.reg" Flags = "1" ErrorControl = "1" Reboot = "False" Timeout = “0”>
   <DisplayName Value = "Notepad Shell" />
   <Description Value = "Changes the Windows Shell to the Notepad Application." />
</RunOnceCommand>

The WindowsShell.reg file would have the following contents:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon]
"Shell"="notepad.exe C:\Windows\POSReadySetup.log"

The &lt;DisplayName&gt; Element

Syntax:

<DisplayName Value="Name_String" />

Name_String contains the name of the <RunOnceCommand>. The name can be up to 64 characters long.

Example:

<DisplayName Value="Microsoft SQL Server 2005 Express Setup" />

The &lt;Description&gt; Element

Syntax:

<Description Value="Description_String" />

Description_String contains a description of the <RunOnceCommand>. The description can be up to 256 characters long.

Example:

<Description Value="This RunOnce Command installs Microsoft SQL Server 2005 Express" />