Jinx Settings
[JINX]
classes = Comma or new line delimited list of classes to load.
error_handler = How to deal with errors.
developer_mode = When enabled (default) the developer tools are added to the Jinx menu.
external_config = Paths of additional config files to load.
optional_external_config = Paths of additional optional config files to load.
startup_script = Path or URL of startup script.
ribbon_xml_file = Filename of ribbon XML file to load.
ribbon_xml_resource = Resource name of ribbon XML to load.
shadow_path = Optional path to use for copying anything on the class path to before loading.
reload_exclude = Optional list of classes (or wildcards) to exclude when reloading.
reload_include = Optional list of classes (or wildchads) to include when reloading.
object_cache_transient_ttl = Time in seconds before transient object references are released.classes
When Jinx starts it loads each classes listed and scans them for Jinx annotations. Annotated methods are registered as Excel functions.
These classes must be available on the classpath (set in the Java section of the config file).
error_handler
This may be set to one of:
- default
- quiet
- none
- a customer error handler class
See Error Handling for details.
developer_mode
Enabled (1) by default. When enabled the developer tools are added to the Jinx menu on the Add-Ins Excel toolbar. If the Add-Ins toolbar isn’t visible it can be added by right clicking on the ribbon and going to Customize.
The developer tools include reloading the Jinx add-in for testing and developing without restarting Excel, and opening the log file.
When deploying to end users who do not need this functionality developer_mode can be set to 0.
external_config
This setting may be used to reference another config file (or files) located elsewhere.
For example, if you want to have the main jinx.ini installed on users’ local PCs but want to control the configuration via a shared file on the network or URL you can use this to reference that external config file.
Multiple external config files can be used by setting this value to a list of file names (comma or newline separated) or file patterns.
Values in external config files override what’s in the parent config file, apart from pythonpath, modules and external_config which get appended to.
In addition to setting this in the config file, the environment variable JINX_EXTERNAL_CONFIG_FILE can be used. Any external configs set by this environment variable will be added to those specified in the config.
optional_external_config
New in Jinx 2.5
This is the same as the external_config option but doesn’t raise an error if the file doesn’t exist.
This can be used to provide optional user specified config where the user may or may not choose to create their own additional config file.
startup_script
Path or URL of a batch or Powershell script to run when Excel starts.
This script will be run when Excel starts, but before Java is initialized. This is so that the script can install anything required by the add-in on demand when Excel runs.
See startup script for more details.
ribbon_xml_file
Filename of a ribbon XML file to load. This may be an absolute path, or a path relative to the config file.
See Ribbon Toolbars for more details.
ribbon_xml_resource
Resource name of a ribbon XML file to load. The JAR containing the resource must be on the class path.
See Ribbon Toolbars for more details.
shadow_path
If set, anything on the class_path will be copied to a unique folder under this path before loading any classes. These copies will be cleaned up when no longer needed automatically.
This is useful as when classes are loaded the class loader keeps the jar file open, which prevents other applications from overwriting or deleting them. While developing it is common to recompile code while keeping Excel open and then using Jinx’s reload feature to load the updated classes, and so by copying the jars before loading this ensures that the originals can be overwritten.
If deploying code to a network drive this can also be helpful so that those files can be updated while users still have Excel open.
reload_exclude
When reloading Jinx, the class loader that was used previously to load all the classes is replaced with a new class loader. This means that all the classes will be loaded again into the new class loader and this is how Jinx is able to reload user code without restarting Excel.
Some classes do not work if loaded twice. This can be because some part of their implementation is written as a native library and that part does not get re-initialized when the Java classes are reloaded.
The reload_exlcude setting is a comma (or new-line) separated list of classes (or wildcards, e.g.
com.microsoft.sqlserver.jdbc.*) that will never be reloaded. Instead, these classes are loaded by a different
class loader that is not replaced until Excel restarts.
reload_include
Instead of including certain classes from being reloaded, if reload_include is set only those classes listed will be reloaded when reloading Jinx.
The reload_include setting is a comma (or new-line) separated list of classes (or wildcards, e.g.
com.yourcompany.*) that will be included when reloading.
reload_include and reload_exclude can be combined. In the case a class matches both reload_exclude and
reload_include, the one that more specifically matches the class will be used. For example, if com.a.* was
excluded and com.a.b.* was included, then all classes in the package com.a would be excluded except for any
classes in the package com.a.b.
object_cache_transient_ttl
If a function returning an object handle is called from VBA a transient reference is created that expires after a specified number of seconds. This allows objects to be passed between functions in VBA, while ensuring that no objects are leaked.
This setting controls the default time to live (TTL) of transient object references, in seconds. The default value is 10.
Web Control Settings
New in Jinx 2.5
Jinx can make web requests to fetch files from web servers instead of using a file path. For example, the license_file, external_config and startup_script settings can all use a URL instead of a path to download a file. Jinx will also attempt to ping a license server and download the latest license information, if possible.
The web control used to make these requests can be configured using the options in this section.
Usually these options should not be set as Jinx will detect the correct settings automatically.
webclient_disable_autoproxy
Jinx will attempt to detect your proxy settings automatically if you have AutoProxy configured.
This can be disabled by setting this option to 1.
webclient_autoproxy_logon_if_challenged
If your proxy server requires authentication Jinx will attempt to auto-logon if challenged.
This can be disabled by setting this option to 0.
webclient_proxy
If you connect to the internet through a manually configured proxy server, and Jinx is not detecting that proxy server automatically, this can be used to set the proxy server.
webclient_proxy_bypass If you connect to the internet through a proxy, and you are manually specifying the proxy server using the webclient_proxy setting above, you can use this setting to configure some sites to bypass the proxy server.
The proxy server will not be used for addresses beginning with entries in this list. Use semicolons (;) to separate entries.
webclient_disable_autologon
If connecting to an Intranet site or trusted URL that supports auto-logon Jinx can try to authenticate automatically.
By default, auto-logon is only used for Intranet requests or Trusted Sites. This can be overridden using the webclient_autologon_security_level setting.
Auto-logon can be disabled by setting this option to 1.
webclient_autologon_security_level
This can be set to low, medium or high and determines what type of sites can be sent credentials for authentication.
low: Default credentials may be sent to all servers.medium: Default credentials may be sent for Intranet requests.high: Default credentials cannot be used for authentication.
By default, auto-logon is used for Intranet requests and Trusted Sites. It is recommended in most cases that this setting is not set.
