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

---

The "JsCa" Command

This command is used to start the definition (and creation) of a Windows Installer JSCRIPT based custom action which ends when the /JsCa 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 JsCaSetup command) with the JsCaEntry and /JsCaEntry commands. You place your code between these two commands. You may define contants and common initialization code above the first use of "JsCaEntry".

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.

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).

• 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 JSCA_PAUSE macro. This is configured from the macro "SUNDRY_CA_PAUSE" (defaults to "N").

• Data (optional)
  Unlike when used on the "JsCaSetup" 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).

Main "JsCa" Options

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

;----------------------------------------------------------------------------
;--- General Options --------------------------------------------------------
;----------------------------------------------------------------------------
#define? DEFAULT_JSCA_CAD_DELIMITER        ,_,              ;;Must be 1-9 characters long
#define? JSCA_LOGDIR_ENVVAR                MAKEMSI_LOGDIR
#define? JSCA_LOG_OK_ENVVAR                MAKEMSI_LOG      ;;Set this environment variable to N to disable logging
#define? JSCA_LOGDIR_EXP_4_DEFAULT         "C:\\"           ;;By default place in C:\ (can be any JSCRIPT expression)
#define? JSCA_LOGFILE_BASENAME_PREFIX      MAKEMSI_JSCA-
#define? DEFAULT_JSCA_SEQTABLE             InstallExecuteSequence
#define? JSCA_OUT_DIR                      <$MAKEMSI_OUT_LOG_DIR>Jscripts
#define? JSCA_INC_BY_SPACE_COUNT           4
#define? JSCA_ROW_@VALIDATE                NEW                ;;See the "@Validate" parameter of the "ROW" command
#define? JSCA_PAUSE                        <$SUNDRY_CA_PAUSE> ;;Debug pauses (Y/N)
#define? JSCA_DISABLED                     <$SUNDRY_DISALLOW_USE_OF_SCRIPT_CUSTOM_ACTIONS> ;;Make non blank to disable (text is error message)
#define? JSCA_DEFAULT_TYPE_ATTRIBUTES
#define? JSCA_BINARY_DOCO                  Y                  ;;"N" = Don't add to doco
#define? JSCA_BINARY_COMMENT               This file generated by the "JsCa" command at <??RxMmLocation>

;----------------------------------------------------------------------------
;--- Custom Action conditions -----------------------------------------------
;----------------------------------------------------------------------------
#define? JSCA_CONDITION_INSTALL_ONLY    <$CONDITION_INSTALL_ONLY>
#define? JSCA_CONDITION_UNINSTALL_ONLY  <$CONDITION_UNINSTALL_ONLY>

EXAMPLE

;--- Create a JSCRIPT and add to the binary table ---------------------------
<$JsCa Binary="SimpleCa.js">
    var some = 1

    <$JsCaEntry "Install">
    {
        try
        {
            CaMsgBox("E", "test of the error box")
        }
        catch(e)
        {
            CaDebug(0, "Install_1 function: trapped")
        }
    }
    <$/JsCaEntry>

    <$JsCaEntry "UnInstall">
        UserFunction("Uninstalling...")
    <$/JsCaEntry>

   //==========================
   function UserFunction(Text)
   //==========================
   {
       CaDebug(0, "Doing something...")
       CaMsgBox("I", Text)
       CaDebug(0, "Finished doing something...")
   }
<$/JsCa>

;--- Call the above script during install and uninstall ---------------------
<$JsCaSetup Binary="SimpleCa.js" Entry="Install"    Deferred=Y Seq="InstallFiles-" CONDITION=^<$CONDITION_INSTALL_ONLY>^>
<$JsCaSetup Binary="SimpleCa.js" Entry="UnInstall"  Deferred=Y 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). Wednesday June 25 2008 at 7:16pm Visit MAKEMSI's Home Page