RunCmd

MAKEMSI quickly and reliably creates MSI files in a non-programmatic way

Source Code

Commands

RunCmd

The "RunCmd" Command

This MAKEMSI command will execute any command line which can be executed on a Windows command prompt and can examines its return code to determine if it succeeded or not.

This command supports the definition of lines of text between this command and any terminating "/RunCmd". The meaning of the lines depends on the "@" parameter's value.

This command takes these parameters:

@ (optional)
You should supply a "N" or "Y" (the default) value.
If "N" is used then you don't wish to create a file but have an easy way to supply extra command line parameters which will be appended to any that you have already supplied (on the "COMMAND" parameter).
If "Y" then a temporary file will be created at runtime and you will refer to it on your command line (the "COMMAND" parameter) as "{?}". A lot of programs would want the filename preceeded by a "@" symbol.
Command (optional)
This is the command line (program and parameters) you wish to run. It is executed via the windows command processor.
Note that this command does not accept normal MSI formatting but see the "DATA" parameter if you need to pass information.
It is possible to define "DEFAULT_RUNCMD_COMMAND", and not specify this parameter, but if not defined by you this parameter is mandatory.
File (optional)
If this parameter is used to supply a filename then you must not use the "/RunCmd" command and the specified files contents will be used.
KeepIndent (optional)
You should supply a "Y" or "N" value. It determines whether or not to keep leading whitespace on the file lines.
The default for this parameter can be set via the DEFAULT_RUNCMD_KEEPINDENT macro. The initial value for this is "Y".
NextID (optional)
You should supply a "Y" or "N" value. It determines whether PPWIZARD "#NextId" processing occurs over the files contents.
The default for this parameter can be set via the DEFAULT_RUNCMD_NEXTID macro. The initial value for this is "Y".
Alias (optional)
The "SQL" command is an alias of the "RUNCMD", this parameter can be used to indicate this, certain messages etc get tweeked.
For example the "SQL" commands are defined as:
```
#define Sql  <$RunCmd  {$?} ALIAS="SQL">
#define /Sql <$/RunCmd {$?} ALIAS="/SQL">
```
RcOk (optional)
By default the processing will abort if a non-zero return code is detected from your "COMMAND". If you don't care at all then pass "". If there is a specific return code it returns on error (for example "4") then specify this, otherwise supply a "test expression" such as "? <= 4" where "?" represents the return code.
Data (optional)
This parameter should only be used if this "run command" is running deferred. The parameter specifies the name of a previously generated 2 column "#data" structure..
The "VbsCaCadReplace" function will be run over both the command and the files contents.
Seq (optional)
Actions are executed in sequence number order and some actions (or types of) are only allowed at certain "locations". This parameter allows you to specify when this action should be executed in relation to others. The fact that MAKEMSI successfully sequences your action at a particular location should not be assumed to mean that it is valid for it to be there.
There will typically be a lot of standard actions at known fixed locations (which may however differ in sequence number or even order relative to one another with different templates). Click here for the default "InstallExecuteSequence" and "InstallUISequence" sequencing details.
Normally you try not to duplicate sequence numbers but it is probably OK to do so as long as you don't care which one executes first! One possible exception would be deferred custom actions where the custom action data needs to be setup before execution. You should get a validation message to indicate a duplicated number (note that validation can't know whether custom action conditions are mutually exclusive etc).
The sequencing information (see some default sequencing) can be supplied in a number of formats:
- An Integer
  If you supply a number such as "1001" then this is a literal numeric value which generally should not duplicate any other in the same table. I suggest you only use this format as a last resort!
- A VBSCRIPT Expression
  If the value you supply starts with "@" then what follows is the name of a VBSCRIPT variable or expression which will evaluate to a sequence number.
- A MAKEMSI Expression
  MAKEMSI has its own syntax which describes the characteristics of the desired sequence number but leaves the actual value up to MAKEMSI to determine.
  Basically you describe a range of valid values and whether you prefer the value to be chosen from the lower (default) or higher end.
  The range should be specified in the format "lower - higher". Either value can be omitted, be specified as an integer such as "1000" or the name of an action such as "InstallFiles". The default value for the lower end is "1" and for the higher "32767" and leading and trailing spaces for each are stripped. The minimum and maximum values can be returned as the range is inclusive.
  By default MAKEMSI will choose a number as close as possible to the lower end, if you wish it to be as high as possible then begin the specification string with "<".
  Some Examples:
  - InstallFiles-
  - -InstallFiles
  - <-InstallFiles
  - < 1000 - 2000
  - AppSearch - CostFinalize
  You should of course be aware of what your script does, for example if it moves a custom action that you have already sequenced other actions relative to then that would probably be "bad"!

Condition (optional)
This identifies the conditions under which the code should be executed. Any properties you set should be available before the "CostFinalize"" action.

I have captured a large number of "sample properties" which could be used in any conditions. Note that the values of some properties may not be available at all times and in some cases are modified during processing.

You can also use any of the following predefined conditions:

#define? CONDITION_ALREADY_INSTALLED Installed                          ;;Repair, uninstall etc.
#define? CONDITION_INSTALL_ONLY      not Installed                      ;;Doesn't include a repair, uninstall etc!
#define? CONDITION_UNINSTALL_ONLY    Installed and REMOVE~="ALL"        ;;Complete uninstall  - HIGHLY RECOMMENDED at you read the "REMOVE" properties MAKEMSI doco!
#define? CONDITION_EXCEPT_UNINSTALL  not (<$CONDITION_UNINSTALL_ONLY>)  ;;Install, Repair etc (all but complete uninstall)
#define? CONDITION_IS_WIN2000        VersionNT = "500"                  ;;Is OS WIN2000?
#define? CONDITION_IS_WINXP          VersionNT = "501"                  ;;Is OS WINXP?
#define? CONDITION_IS_VISTA          VersionNT = "600"                  ;;Is OS WINDOWS Vista?
#define? CONDITION_IS_WINDOWS_7      VersionNT = "601"                  ;;Is OS WINDOWS Windows7
#define? CONDITION_UI_NONE           UILevel = 2                        ;;Silent Install
#define? CONDITION_UI_BASIC          UILevel = 3
#define? CONDITION_UI_REDUCED        UILevel = 4
#define? CONDITION_UI_FULL           UILevel = 5                        ;;"Normal"
#define? CONDITION_UI_NO_DIALOGS     UILevel <> 5                       ;;Don't bother user with popup dialogs, opening readme files etc.
#define  CONDITION_PER_MACHINE       Version9X or (ALLUSERS = 1)        ;;True if per-machine install.
#define  CONDITION_PER_USER          not (<$CONDITION_PER_MACHINE>)     ;;True if per-user (not per-machine) install.

Type (optional)
This parameter may not be required for all custom action types, it provides a mechanism to override, update or undo any options that MAKEMSI may have decided to use.
This parameter accepts one or more space separated attributes which are processed in left to right order. Available attributes are (not all may apply):
1. Deferred
  This indicates that the custom action should be run deferred (not immediately). The opposite to the "Immediate" attribute and the default for most custom action types. If its deferred the "Description" will be displayed in the progress bar (line 1).
  A deferred (in-script) custom action must be sequenced between the "InstallInitialize" and "InstallFinalize" actions (or you will get a 2762 error) and data is passed via the "CustomActionData" property.
  All deferred actions are executed in a single pass by the server "MSIEXEC.EXE" service (a separate process) after being combined in a "script".
2. Immediate
  The "immediate" attribute is the opposite of "deferred".
  All immediate custom actions scheduled between the "InstallInitialize" and "InstallFinalize" actions (regardless of their sequence number) are executed before deferred ones.
3. Sync
  This indicates that Windows Installer should wait for the custom action to complete. The opposite to the "ASYNC" attribute and this is the default.
4. ASync
  The opposite to the "SYNC" attribute..
5. Rc0
  This indicates that the RUNCMD indicates success by returning a return code of 0. The opposite to the "AnyRc" attribute.
6. AnyRc
  The opposite to the "Rc0" attribute. The return code should be ignored.
  This should only be used as a last resort when executing some poorly written piece of "cr*p" (or perhaps if it's success is not critical to the install).
7. Commit
  This indicates that the custom action is a "commit" custom action.
8. Rollback
  This indicates that the custom action is a "rollback" custom action. It should be sequenced before the custom action being rolled back and have the same condition.
  Rollback custom actions (and so also the "worker" custom action) must be "deferred" and sequenced between "InstallInitialize" and "InstallFinalize".
9. Impersonate
  The custom action should be run under user-level privileges. This is the default. The opposite to the "System" attribute.
  There are circumstances where a custom action may still run with system privileges.
10. System
  The custom action should be run under the system account (elevated). The opposite to the "Impersonate" attribute.
  Lack of this attribute on deferred custom actions is a common reason for failures on Vista.
11. FirstSequence
  No effect in UI sequence. If the "UI sequence" did run and this action is in the "Execute sequence" then it won't run (whether or not your custom action is sequenced in the UI)
12. OncePerProcess
  Execute once per process if in both sequence tables. Skips action in execute sequence if UI sequence has been run in same process, for example both run in the client process. Used to prevent actions that modify the session state, such as property and database data, from running twice
13. ClientRepeat
  Execute only if running on client after UI sequence has run. The action runs only if the execute sequence is run on the client following UI sequence. May be used to provide either/or logic, or to suppress the UI related processing if already done for client session.
14. 64BitScript
  This is a 64-bit script based custom action. Form more information see the "64 Bit Installs" section.
15. HideTarget
  The installer is prevented from writing the value in the Target column of the CustomAction table into the log file.
  The CustomActionData property is also not logged when the installer executes the custom action.
  Because the installer sets the value of CustomActionData from a property with the same name as the custom action, that property must be listed in the "MsiHiddenProperties " property to prevent its value from appearing in the log.
16. TSAware
  Not sure, Microsoft don't document it (good one). If you have any issues with MSIs under terminal services then I'd guess this would be a good flag to try!
17. PatchUninstall [4.5+]
  Used to define a custom action that only runs during the uninstallation of a patch.
18. +[0x]Number
  A value beginning with "+" indicates that you wish to set (add) attribute(s)/bit(s).
  If the number begins with "0x" (case insensitive) then the number is being supplied as a hexadecimal value otherwise its interpreted as being in decimal.
  You may need to supply a numeric value such as "+0x0001" if I haven't provided a suitable alias above...
19. -[0x]Number
  A value beginning with "-" indicates that you wish to reset (remove) bit(s).
20. =[0x]Number
  A value beginning with "=" indicates that you wish to set the custom action type to a specific value. This will completely override any other attributes that may have been previously specified internally by the MAKEMSI command or by you. This should rarely if ever be required

RUNCMD Options/Defaults

Please see the "options for commands" section of the manual.

#define? DEFAULT_RUNCMD_COMMAND
#define? DEFAULT_RUNCMD_KEEPINDENT      Y
#define? DEFAULT_RUNCMD_NEXTID          Y          ;;"@@" etc will be converted
#define? RUNCMD_CAD_SYMBOL_START        (*         ;;(*CadSymbolName*)
#define? RUNCMD_CAD_SYMBOL_END          *)         ;;(*CadSymbolName*)
#define? RUNCMD_FROM_SOURCE_FILE \
         <$SourceFile FileName="{$FileName}" Html="Y"> ;;Add to HTML report
#define? RUNCMD_SEQUENCE_NUMBER         DuplicateFiles-InstallFinalize

EXAMPLE - RUNCMD via SQL Aliases

The following example uses the "OSQL.EXE" which is expected to be available on the installed system. Note that "OSQL.EXE" uses the "-i" option to specify the name of an input file.

;--- Use existing ".SQL" file -----------------------------------------------
<$Sql file="Update.SQL" Command=^"osql.exe" -E -b -n -w512 -S . -d "DatabaseName" -i "{?}"^>

;--- .SQL inline ------------------------------------------------------------
#define MySqlCmd  osql.exe -E -b -n -w512 -S . -d "DatabaseName" -i "{?}"
<$Sql Command=^<$MySqlCmd>^>
   Delete from
       INF_Router
   Where
       ID_Process = 18 and ProcessName = 'GetAllDBUsers'
   GO

   Delete from
       INF_Error
   Where
       ID_Source = 'Operator.GetXMLForAllDBOperators'
   GO
<$/Sql>
<$Sql Command=^<$MySqlCmd>^>
      #include "SqlPart1.SQL"
      #include "SqlPart2.SQL"
<$/Sql>

This example uses "MySql" an gets the database name from a Windows Installer property:

#data "CaSqlData"
      "Database" "[DBNAME]"     ;;DBNAME comes from dialog (or command line if silent)
#data

#define MySqlCmd "mysql.exe" --user=root --password=PASSWORD1 < "{?}"
<$Sql Command=^<$MySqlCmd>^ DATA=^CaSqlData^>
      CREATE DATABASE IF NOT EXISTS (*Database*);
<$/Sql>

#define MySqlCmd2 "mysql.exe" --user=root --password=PASSWORD1 < "{?}"
<$Sql Command=^<$MySqlCmd2>^ DATA=^CaSqlData^>
    USE (*Database*);
    #include "query.sql"
<$/Sql>

Example - Use CACLS.EXE

The following example shows how some macros could be used to set up some comamnds which invoke "cacls.exe" to set or modify ACLs:

;--- Handy commands you may wish to use -------------------------------------
#define  CACLS   <$RunCmd  {$?} ALIAS="CACLS" Command="CACLS.EXE" @="N">    ;;"CACLS.EXE" installed with WIN2000 & WINXP (at least on PRO)
#define  /CACLS  <$/RunCmd {$?} ALIAS="/CACLS">

;--- Update ACL on "fred.ini" -----------------------------------------------
<$CACLS CONDITION=^<$CONDITION_INSTALL_ONLY>^>
    ;--- Name of file we wish to modify ACL on ------------------------------
    "%WinDir%\system32\fred.ini"

    ;--- Edit ACL instead of replacing it -----------------------------------
    /E

    ;--- Deny administrators access -----------------------------------------
    /D administrators
<$/CACLS>

The example below makes use of the same macros used above but shows a how you can reference the installation directory (or msi properties in general):

#data '@@INSTALLDIR' 2
    ;--- Install time name and location of SETACL tool ----------------------
    "INSTALLDIR" "[INSTALLDIR]"
#data
<$CACLS CONDITION=^<$CONDITION_INSTALL_ONLY>^ DATA="@@INSTALLDIR">
   "(*INSTALLDIR*)SomeFile.txt"
   /E
   /G Users:C
<$/CACLS>

You could use the "ExeCa" command to execute the program without a script (which you may wish to do) however these are some of the disadvantages:

You will have reduced (almost no) logging.
Better error messages presented to user, giving you a much better chance of quickly resolving any problems.
More limitations on return code handling.

Microsoft awarded me an MVP (Most Valuable Professional award) in 2004, 2005, 2006, 2007, 2008 & 2009 for the Windows SDK (Windows Installer) area.

Please email me any feedback, additional information or corrections.
See this page online (look for updates)