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

If imbedding within a macro please ensure that the "current" line continuation is "<?NewLine>".

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)
  If the value:

  1. Doesn't start with '!' character then:

     This command will store the generated script in the "Binary" table under this key. You will refer to this key in a later "VbsCaSetup" command.

     MAKEMSI supplies a lot of error checking and routines to binary scripts (see the "custom action functions" section).

  2. Starts with '!' then:

     The script will be stored under this name and referred to in the later "JsCaSetup" command to create a type 37 (inline) custom action.

     Inline scripts are intended for short (non-deferred) simple scripts and:

     1. MAKEMSI doesn't add any supporting routines of any type (what you see is what you get).

     2. MAKEMSI removes any lines starting with "//" (jscript comment characters) as they would only use up space. MAKEMSI line and inline comments are as you'd expect always removed.

     3. MAKEMSI takes care of any problem characters such as '['.

     Its probable that in some environments an "inline" script may not trigger script alerts which a binary one would (at least with default options) because of the extra processing performed by these by default.

  Scripts of both types are syntax checked during MAKEMSI's processing.

• 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_INC_BY_SPACE_COUNT              4
#define? JSCA_ROW_@VALIDATE                   NEW                         ;;See the "@Validate" parameter of the "ROW" command
#define? JSCA_ROW_@VALIDATE_INLINE            NEW -Target:STRINGOVERFLOW  ;;See the "@Validate" parameter of the "ROW" command (lets allow the script to exceed the columns 255 character width)
#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_DEFAULT_TYPE_ATTRIBUTES_INLINE  immediate           ;;For inline (in CA table) based CA
#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 - Very Simple INLINE Custom Action to Remove Trailing Backslash

<$JsCa Binary="!SimpleJS">
     var InstallDir = Session.Property("INSTALLDIR");
     InstallDir = InstallDir.slice(0, -1);              ;;Remove last character (\) from the path
     Session.Property("DIR_NO_SLASH") = InstallDir      ;;You will see this action logged in any verbose log
<$/JsCa>
<$JsCaSetup Binary="!SimpleJS" Seq="CostFinalize-" SeqTable="InstallExecuteSequence" CONDITION=^<$CONDITION_INSTALL_ONLY>^>

See the "Remove Trailing Slashes from Directory Names" tip for some other languages.

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). Saturday May 28 2022 at 3:11pm Visit MAKEMSI's Home Page