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

---

The "VbsCa" Command

This command is used to start the definition (and creation) of a Windows Installer VBSCRIPT based custom action which ends when the /VbsCa command is encountered. The generated script is automatically added into the "Binary" table. You should be aware of the "Norton's Malicious Script Detection" issue.

If you have an existing Windows Scripting Host (WSH) script which you want to use, use the "ExeCa" command to invoke "WSCRIPT.EXE". All parameters will typically be passed on the command line and no logging will take, in my mind good reasons why this should be avoided at nearly all costs.

You will indicate the function entry points (which you will schedule via the VbsCaSetup command) with the VbsCaEntry and /VbsCaEntry commands. You place your code between these two commands. You may define contants and common initialization code above the first use of "VbsCaEntry".

I highly recommend the use of the CaDebug function and will be reluctant to look at any user supplied code which doesn't make use of it to indicate progress and to make the code easier to debug when it fails.

The generated script has these main characteristics:

• As Windows Installer is running the script and not WSH, you can't make use of the normally predefined "wscript" object (wscript.CreateObject, wscript.sleep etc).

• At least by default all variables must be declared. To debug "unknown variables", make good use of "CaDebug()" and try executing the the custom action as a script from the command line (You will then see the line and variable details).

• Most of the script is generated by this command and is therefore common to all your custom action scripts and well tested.

• The CA based script can be tested from the command line! It takes a single parameter which is the name of the "entry point" to be tested. If not passed then the first specified by you is executed. This does of course assume that the function the entry point performs can function (or has been made to function) when not run via Windows Installer.

• The progress bar is updated as to the stage your script is at.

• It simplifies access in a deferred custom action to "CustomActionData" (parameters).

• The script will log into any MSI log that Windows Installer might be creating.

• By default a log file is also generated.

• It handles traps. You code should use "on error resume next" for as short a period as possible and if required use "VbsCaRaiseError" on failure.

• The VBS you create for execution as a custom action can be generated to contain constants or literals to represent variable information rather than have the information passed to it. This can make it easier to "pass" information to the custom action.

You should have a look at the "custom action functions" section.

Microsoft actually have some very useful script information and samples at "http://www.microsoft.com/technet/scriptcenter/default.mspx". I have a collection of other useful scripting links at "http://dennisbareis.com/bookmark_developer_windows_scripting_host.htm".

Parameters

This command takes these parameters:

• Binary (required)
  This is the key that you wish the generate script to be stored under in the "Binary" table.

• Line1 (optional)
  This is the prefix of any text displayed in the progress bar on line 1. Note that this prefix is only used on messages which don't go to the progress bar and sent using the CaDebug function.

• ErrorRc (optional)
  This has a default value of "1603" which will cause rollback when an error occurs. You could set this to "0" if you had a non-critical script which you did not wish to force an install abort if it failed.

• LogFile (optional)
  This is the full name of the logfile, if not specified one is created in the "c:\" directory (directory can be overriden with environment variable on machine where install is taking place).. If you specify "" then no logging takes place. Note that this only effects the logging file, normal logging to any Windows Installer log will still occur (not effected by this parameter).

• OptCode (optional)
  Some routines are optional, this gives you the option of reducing the size of your generated scripts by indicating parts that you won't (or will) use.

  The following code can be excluded/included in the generated script:

  • CaDeleteFile().
  • CaSleep().
  • VbsCaCadGetValidate().

  The defaults for all optional code are indicated by the individual definitions shown here:

  ;--- Defaults for the "OptCode" parameter -----------------------------------
  #define? VBSCA_WANT_VbsCaCadGetValidate   Y     ;;Want VbsCaCadGetValidate() Y/N?
  #define? VBSCA_WANT_CaDeleteFile          Y     ;;Want CaDeleteFile() Y/N?
  #define? VBSCA_WANT_CaSleep               N     ;;Want CaSleep() Y/N? - wscript.sleep unavailable in CA!

  To override the above defaults, this parameter should be passed one or more space separated specifications, each of which being the name of a piece of code. If preceeded by "-" then you don't want the code included, "+" (or anything else) to include. An error is generated if an unknown option is specified.

  If you indicate you don't need some code which you actually need then you will either get an unknown variable or type mismatch error and because Microsoft don't provide any error/location details (variable names, line numbers etc) in their error messages, debugging a missing script will be difficult (and a good reason for using many CaDebug() calls). Have a chat to Microsoft if you don't like this...

  It is possible for you to define your own optional code, see:

  ;--- We need to define all possible values which can be used in for "OptCode" ---
  #define? VBSCA_OPCODE_LIST_USER_DEFINED         ;;List of ";" delimitered user defined routines/keywords (user must also create "VBSCA_WANT_?" definitions like the above)
  #(  ';'
      #define VBSCA_OPCODE_LIST                   ;;User shouldn't override this! Here for visibility.
  
      ;--- Add MAKEMSI defined to list ----------------------------------------
      CaDeleteFile
      CaSleep
      VbsCaCadGetValidate
  
      ;--- Add user defined to list -------------------------------------------
      <$VBSCA_OPCODE_LIST_USER_DEFINED>
  #)

• Define (optional)
  You can pass "N" or "Y" for this parameter, it determines whether or not you wish to require that all VBS variables be defined.

  If you are having trouble getting your script to work and can't work out why then use "N" for this parameter and get it working that way first before changing back.

  The default for this parameter can be set via the DEFAULT_VBSCA_MUST_DEFINE_VBS_VARIABLES macro. This is initially "Y".

• Doco (optional)
  Should VbsCa information is placed into the generated HTML report (Y/N)?

  The default for this parameter can be set via the DEFAULT_VBSCA_DOCO macro. The initial value for this is "Y".

• Pause (optional)
  You can pass "N" or "Y" for this parameter to select whether or not debug pauses (CaDebugPause()) should be executed at certain times.

  This can be handy if you are wondering about sequencing (for example is my custom action executing before or after files are installed etc). A message will be displayed pausing installation, you can then use explorer or other tools to examine your computer.

  The default for this parameter can be set via the VBSCA_PAUSE macro. This is configured from the macro "SUNDRY_CA_PAUSE" (defaults to "N").

• Data (optional)
  Unlike when used on the "VbsCaSetup" command this parameter is only handy to use if you are creating a deferred custom action which you will or may test from the command line (it does not affect operation of the script when running as a custom action). The purpose is to supply a default value for the prompt which "VbsCaCadGet" will display.

Main "VbsCa" Options

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

;----------------------------------------------------------------------------
;--- General Options --------------------------------------------------------
;----------------------------------------------------------------------------
#define? DEFAULT_VBSCA_MUST_DEFINE_VBS_VARIABLES Y
#define? DEFAULT_VBSCA_CAD_DELIMITER             ,_,                 ;;Must be 1-9 characters long (and something your parameters won't contain)
#define? VBSCA_CmdLineTrapsHandledByVb           true                ;;Best way for testing script from command line (given how lame "err" object and its support is)
#define? DEFAULT_VBSCA_SEQTABLE                  InstallExecuteSequence
#define? VBSCA_INC_BY_SPACE_COUNT                4
#define? VBSCA_ROW_@VALIDATE                     NEW                 ;;See the "@Validate" parameter of the "ROW" command
#define? VBSCA_PAUSE                             <$SUNDRY_CA_PAUSE>  ;;Debug pauses (Y/N)
#define? VBSCA_DISABLED                          <$SUNDRY_DISALLOW_USE_OF_SCRIPT_CUSTOM_ACTIONS>  ;;Make non blank to disable (text is error message)
#define? VBSCA_DEFAULT_TYPE_ATTRIBUTES
#define? DEFAULT_VBSCA_DOCO                       Y                   ;;"N" = Don't add to doco
#define? VBSCA_BINARY_COMMENT                    This file generated by the "VbsCa" command at <??RxMmLocation>
#define? VBSCA_CADEBUG_FORMAT_LINE12             {{[Time]: }}[1]      ;;Time only visible in log! MUST include "[1]"
#define? VBSCA_CAMSGBOX_PREFIX_ERROR             ERROR: [1]           ;;Windows Installer message template for ERROR messages
#define? VBSCA_CAMSGBOX_PREFIX_INFO                                   ;;Windows Installer message template for INFO messages
#define? VBSCA_CAMSGBOX_PREFIX_OTHER                                  ;;Windows Installer message template for "other" messages
#define? VBSCA_VBEXP_CURRENT_DATE                FormatDateTime(now(), vbShortDate)
#define? VBSCA_VBEXP_CURRENT_TIME                FormatDateTime(now(), vbLongTime)



;----------------------------------------------------------------------------
;--- Logging Related --------------------------------------------------------
;----------------------------------------------------------------------------
#define? VBSCA_LOG_TO_FILE.D                     Y                   ;;Logging OK in development
#define? VBSCA_LOG_TO_FILE.P                     N                   ;;Logging may trigger the dodgy Norton Antivirus, if not issue (or you are doing file IO in any case) then turn on!
#define? VBSCA_LOG_TO_FILE                       <$VBSCA_LOG_TO_FILE.[MMMODE]>
#define? VBSCA_LOG_OK_ENVVAR                     MAKEMSI_LOG         ;;Set this environment variable to N to disable logging
#define? VBSCA_LOGDIR_ENVVAR                     MAKEMSI_LOGDIR      ;;Set this environment variable to directory for logging
#define? VBSCA_LOGDIR_EXP_4_DEFAULT              "C:\"               ;;By default place in C:\ (can be any VBS expression)
#define? VBSCA_LOGFILE_BASENAME_PREFIX           MAKEMSI_VBSCA-
#define? VBSCA_LOGFILE_BASENAME_MIDDLE           <$ProdInfo.ProductName>(<$ProductVersion>)
#define? VBSCA_LOGFILE_BASENAME_SUFFIX           -" & WeekDayName(Weekday(date())) & "   ;;Can help to reduce likelyhood that lots of logging will cause truncation
#define? VBSCA_LOGFILE_EXTENSION                 .log
#define? VBSCA_LOGFILE_EXP_4_DEFAULT_BASENAME    "<$VBSCA_LOGFILE_BASENAME_PREFIX><$VBSCA_LOGFILE_BASENAME_MIDDLE><$VBSCA_LOGFILE_BASENAME_SUFFIX><$VBSCA_LOGFILE_EXTENSION>"   ;;Any VB Expression ("BINARY" parameter is passed)
#define? VBSCA_LOGFILE_MAX_AGE_IN_DAYS           100                 ;;If older than this then whole file removed prior to logging starting (0=Do Nothing)
#define? VBSCA_LOGFILE_MAX_SIZE_IN_K             300                 ;;If bigger than this many K then shorten (before logging - so log can grow larger than this)
#define? VBSCA_LOGFILE_REDUCE_TO_PERCENTAGE      75                  ;;If log is too big then reduce it to what percentage of max size?
#define? VBSCA_LOG_EXP_4_ADD_2_HEADER                                ;;Define to hold appropiate calls to "CaDebug"


;----------------------------------------------------------------------------
;--- Allow overriding of default logging behaviour --------------------------
;----------------------------------------------------------------------------
#define? VBSCA_DEBUG1  CaDebug 1,           ;;Line 1 output goes to line 1, allow redirection, example: CaDebug 0,
#define? VBSCA_DEBUG2  CaDebug 2,           ;;Line 2 output goes to line 2
#define? VBSCA_DEBUG0  CaDebug 0,           ;;Log    output goes to log.


;----------------------------------------------------------------------------
;--- Custom Action conditions -----------------------------------------------
;----------------------------------------------------------------------------
#define? VBSCA_CONDITION_INSTALL_ONLY    <$CONDITION_INSTALL_ONLY>
#define? VBSCA_CONDITION_UNINSTALL_ONLY  <$CONDITION_UNINSTALL_ONLY>

EXAMPLE - Simple IMMEDIATE Custom Action

;--- Simple immediate CA ----------------------------------------------------
<$VbsCa Binary="ImmediateExample.vbs">
   <$VbsCaEntry "EntryPoint">
        dim Version : Version = session.property("ProductVersion")
        session.property("CREATE_NEW_PROPERTY") = "This product is version " & Version ;;Should see in "verbose" install log
   <$/VbsCaEntry>
<$/VbsCa>

;--- Schedule it ------------------------------------------------------------
<$VbsCaSetup Binary="ImmediateExample.vbs" Entry="EntryPoint" Seq="<-LaunchConditions" CONDITION="<$CONDITION_INSTALL_ONLY>" Type="immediate FirstSequence" SeqTable="InstallUISequence InstallExecuteSequence">

EXAMPLE - DEFERRED - With CustomActionData

;--- Set up the 2 parameters (CustomActionData) -----------------------------
#data "Fred"
   "Name1" 'Name 1 Value'          ;;Parameter 1 (name + value)
   "Name2" "[INSTALLDIR]"          ;;Parameter 2
#data

;--- Deferred Custom Action which accesses 2 passed parameters --------------
<$VbsCa Binary="TestCustomActionDataPassing.vbs" DATA="Fred">
   <$VbsCaEntry "Install">
       ;--- Do something ----------------------------------------------------
       Show("Install: NAME1=" & VbsCaCadGet("Name1"))
       Show("Install: NAME2=" & VbsCaCadGet("Name2"))
   <$/VbsCaEntry>

   '=======================
   sub Show(Text)
   '=======================
       CaMsgBox "I", Text
   end sub
<$/VbsCa>

;--- Set up the Deferred custom action passing the CustomActionData ---------
<$VbsCaSetup Data="Fred" Binary="TestCustomActionDataPassing.vbs" Entry="Install" Seq="InstallFiles-" CONDITION=^<$CONDITION_INSTALL_ONLY>^>

EXAMPLE

;--- Create a VBSCRIPT and add to the binary table --------------------------
#( '<?NewLine>'
   #define InstallationOnTrap

   ;--- This code must be called to "clean up" after failed install ---------
   'clean up code statement 1
   'clean up code statement 2
   'clean up code statement 3
#)
<$VbsCa Binary="TEST.vbs">
   <$VbsCaEntry "Install" OnTrap="<$InstallationOnTrap>">
       ;--- Do something ----------------------------------------------------
       UserFunction("Called during Install...")

       ;--- Set the return code ---------------------------------------------
       '<$VbsCaEntryName> = 1603         ;;Error Return code
   <$/VbsCaEntry>

   <$VbsCaEntry "UnInstall">
       ;--- Do something ----------------------------------------------------
       UserFunction("Called during UNInstall...")
   <$/VbsCaEntry>

   '=======================
   sub UserFunction(Text)
   '=======================
       CaMsgBox "I", Text
   end sub
<$/VbsCa>

;--- Call the above script during install and uninstall ---------------------
<$VbsCaSetup Binary="TEST.vbs" Entry="Install"   Seq="InstallFiles-" CONDITION=^<$CONDITION_INSTALL_ONLY>^>
<$VbsCaSetup Binary="TEST.vbs" Entry="UnInstall" Seq="InstallFiles-" CONDITION=^<$CONDITION_UNINSTALL_ONLY>^>

Please email me any feedback, additional information or corrections. See this page online (look for updates) MAKEMSI© is (C)opyright Dennis Bareis 2003-2008 (All rights reserved). Thursday August 28 2008 at 11:28am Visit MAKEMSI's Home Page