Startup Script

New in Jinx 2.1

The startup_script option can be used to run a batch or Powershell script when Excel starts, and again each time Jinx is reloaded.

This can be useful for ensuring Java is installed correctly and any Java packages are up to date, or for any other tasks you need to perform when starting Excel.

The script runs before the JVM is initialized, and can therefore be used to set up a Java Runtime Environment if one doesn’t already exist.

The Jinx config can be manipulated from the startup script so any settings such as the classes list, classpath or even java_home can be set on startup rather than being fixed in the jinx.ini file.

The startup script can be a local file, a file on a network drive, or even a URL. Using a network drive or a URL can be a good option when deploying Jinx to multiple users where you want to have control over what’s run on startup without having to update each PC.

Batch files (.bat or .cmd) and Powershell files (.ps1) are supported. Script files must use one of these file extensions.

The script is run with the current working directory (CWD) set to the same folder as the Jinx add-in itself, and so relative paths can be used relative to the xll file.

If successful the script should exit with exit code 0. Any other exit code will be interpreted as the script not having been run successfully by Jinx.

Example

A startup script could be used to download a JAR file and configure Jinx.

REM startup-script.bat
@ECHO OFF

REM If the JAR file already exists no need to download it
IF EXIST ./jars/jar-file-xx.jar GOTO SKIPDOWNLOAD

REM Download the JAR file
wget -P ./jars https://intranet/jars/jar-file-xx.jar 
:SKIPDOWNLOAD

REM Update the Jinx settings with the JAR file
ECHO jinx-set-option JAVA classpath ./jars/jar-file-xx.jar

The script is configured in the jinx.ini file, and could be on a remote network drive or web server.

[JINX]
startup_script = https://intranet/jinx/startup-script.bat

Note: Setting the classpath option using jinx-set-option appends to the existing classpath.

Script Commands

When Jinx runs the startup script (either a batch or Powershell script) it monitors the stdout of the script for special commands. These commands can be used by your script to get information from Jinx, update settings, and give the user information.

To call one of the commands from your script you echo it to the stdout. For example, the command jinx-set-option can be used to set one of Jinx’s configuration options. In a batch file, to set the LOG/level setting to finest it would be called as follows:

ECHO jinx-set-option LOG level finest

Calling the command from Powershell is the same:

Echo jinx-set-option LOG level finest

Some commands return results back to the script. They do this by writing the result to the script’s stdin. To read the result from a command that returns something you need to read it from the stdin into a variable. The command jinx-get-command is one that returns a result and can be used from a batch file as follows:

ECHO jinx-get-option JAVA java_home
SET /p JAVA_HOME=
REM The java_home setting is now in the variable %JAVA_HOME%

Or in Powershell it would look like:

Echo "jinx-get-option JAVA java_home"
$java_home = Read-Host

Below is a list of the available commands.

jinx-get-option

Gets the value of any option from the config.

Takes two arguments, SECTION and OPTION, and returns the option’s value.

  • Batch File

    ECHO jinx-get-option SECTION OPTION
SET /p VALUE=

  • Powershell

    Echo jinx-get-option SECTION OPTION
$value = Read-Host

If used on a multi-line option (e.g. JAVA/classpath and JINX/classes) the value returned will be a list of value delimited by the separator documented for the setting.

jinx-set-option

Sets a config option.

Takes three arguments, SECTION, OPTION and VALUE. Doesn’t return a value.

  • Batch File

    ECHO jinx-set-option SECTION OPTION VALUE

  • Powershell

    Echo jinx-set-option SECTION OPTION VALUE

When used with multi-line options (e.g. JAVA/classpath and JINX/classes) this command appends to the list of values. Use jinx-unset-option to clear the list first if you want to overwrite any current value.

jinx-unset-option

Unsets the specified option.

Takes two arguments, SECTION and OPTION. Doesn’t return value.

  • Batch File

    ECHO jinx-unset-option SECTION OPTION

  • Powershell

    Echo jinx-unset-option SECTION OPTION

jinx-set-progress

Display or update a progress indicator dialog to inform the user of the current progress.

This is useful for potentially long running start up scripts, such as when downloading files from a network location or installing a large number of files.

Takes one argument, the current progress as a number between 0 and 100. Doesn’t return a value.

  • Batch File

    ECHO jinx-set-progress PERCENT_COMPLETE

  • Powershell

    Echo jinx-set-progress PERCENT_COMPLETE

jinx-show-progress

Displays the progress indicator without setting the current progress.

This shows the progress indicator in ‘marquee’ style where it animates continuously rather than showing any specific progress.

If the progress indicator is already shown this command does nothing.

Takes no arguments and doesn’t return a value.

  • Batch File

    ECHO jinx-show-progress

  • Powershell

    Echo jinx-show-progress

jinx-set-progress-status

Sets the status text of the progress indicator dialog.

This does not show the progress indicator if it is not already shown. Use jinx-show-progress or jinx-set-progress to show the progress indicator.

Takes one argument, STATUS, and doesn’t return a value.

  • Batch File

    ECHO jinx-set-progress-status STATUS

  • Powershell

    Echo jinx-set-progress-status STATUS

jinx-set-progress-title

Sets the title of the progress indicator dialog.

This does not show the progress indicator if it is not already shown. Use jinx-show-progress or jinx-set-progress to show the progress indicator.

Takes one argument, TITLE, and doesn’t return a value.

  • Batch File

    ECHO jinx-set-progress-title TITLE

  • Powershell

    Echo jinx-set-progress-title TITLE

jinx-set-progress-caption

Sets the caption text of the progress indicator dialog.

This does not show the progress indicator if it is not already shown. Use jinx-show-progress or jinx-set-progress to show the progress indicator.

Takes one argument, CAPTION, and doesn’t return a value.

  • Batch File

    ECHO jinx-set-progress-caption CAPTION

  • Powershell

    Echo jinx-set-progress-caption CAPTION

jinx-get-version

Gets the version of the installed Jinx add-in.

Takes no arguments and returns the version.

  • Batch File

    ECHO jinx-get-version
SET /p VERSION=

  • Powershell

    Echo jinx-get-version
$version = Read-Host

jinx-get-arch

Gets the machine architecture of the Excel process and Jinx add-in.

Takes no arguments and returns either ‘x86’ for 32 bit or ‘x64’ for a 64 bit.

  • Batch File

    ECHO jinx-get-arch
SET /p ARCH=

  • Powershell

    Echo jinx-get-arch
$arch = Read-Host

jinx-get-pid

Gets the process id of the Excel process.

Takes no arguments and the process id.

  • Batch File

    ECHO jinx-get-pid
SET /p PID=

  • Powershell

    Echo jinx-get-pid
$pid = Read-Host

jinx-restart-excel

Displays a message box to the user informing them Excel needs to restart. If the user selects ‘Ok’ then Excel will restart. The user can cancel this and if they do so the script will be terminated.

This can be used if your script needs to install something that would require Excel to be restarted. When Excel restarts your script will be run again and so you should ensure that it doesn’t repeatedly request to restart Excel.

One possible use case is if you want to upgrade the Jinx add-in itself. You can rename the existing one (it can’t be deleted while Excel is using it, but it can be renamed) and copy a new one in its place and then request to restart Excel.

Takes one optional argument, MESSAGE, which will be disaplyed to the user. Doesn’t return a result.

  • Batch File

    ECHO jinx-restart-excel MESSAGE

  • Powershell

    Echo jinx-restart-excel MESSAGE

© Copyright PyXLL Ltd.