StarQuest Technical Documents

StarSQL for Java Licensing

Last Update: 14 August 2019
Product: StarSQL for Java
Version: 2.2 & later
Article ID: SQV0SJ011

Abstract

Licensing for StarSQL for Java is configured using a file StarLicense.properties. Licensing problems may occur if the JDBC application using StarSQL for Java cannot locate this file.

Solution

• The default location of StarLicense.properties is in the same directory as the StarSQL_JDBC.jar JDBC driver file. In many situations, this is sufficient if this directory (e.g. C:\Program Files\StarQuest\StarSQL_Java or /opt/starsql_java) has been added to CLASSPATH.
• If that fails, we suggest adding the full path to both the jar file and the license file (e.g. C:\Program Files\StarQuest\StarSQL_Java\StarSQL_JDBC.jar; C:\Program Files\StarQuest\StarSQL_Java\StarLicense.properties) to CLASSPATH.
• In some cases, it may be necessary to copy StarLicense.properties to the lib or ext directory of the JRE being used by the application. For example, Adobe ColdFusion users can copy StarLicense.properties to a directory such as D:\ColdFusion9\runtime\jre\lib. This approach is not generally recommended if you are using a public JRE, as the JRE library will be removed when JRE is updated.
• In some cases, it may be necessary to copy or link StarLicense.properties to a working directory of the application. Here are some examples:
  
  • IBM WebSphere Application Server will sometimes ignore the StarLicense.properties file even if it is explicitly included in the CLASSPATH. The workaround is to copy or link a configured StarLicense.properties file into the directory that WebSphere looks for other .properties file. WebSphere typically uses a variable (WAS_PROPS_DIR) that points to the properties folder, and this folder should already be included in the CLASSPATH by WebSphere. You may also want to review the output during the server startup to determine which directories are included in the CLASSPATH and then choose the most appropriate one to host the StarLicense.properties file. Any change typically necessitates a restart of the WebSphere service.
  • DbVis DbVisualizer: Copy or link StarLicense.properties to the lib subdirectory e.g. C:\Program Files\DbVisualizer\lib.
  • DBeaver: Copy or link StarLicense.properties to the plugins subdirectory e.g. C:\Program Files\DBeaver\plugins. Be sure to quit and restart the DBeaver application after making licensing changes; using Disconnect/Connect is not sufficient.
  • IBM Data Studio: Copy or link StarLicense.properties to the plugins subdirectory e.g. C:\Program Files\IBM\DS4.1.3\plugins
  • If you are using multiple JDBC applications, creating multiple copies of StarLicense.properties may cause maintenance or troubleshooting issues in the future.Instead, you can create a link to a master copy. On Windows, use the mklink command in an elevated window; on UNIX, use ln -s. Examples:
    
    mklink "C:\Program Files\dbeaver\plugins\StarLicense.properties" "C:\Program Files (x86)\StarQuest\StarSQL_Java\StarLicense.properties"
    
    ln -s /usr/share/starsql_java/StarLicense.properties /opt/myapp/lib
    
    
• Using DNS: If StarSQL for Java cannot locate StarLicense.properties, its default behavior is to attempt to connect to a StarLicense server with a hostname of starlic, listening on port 4999. If your environment includes a StarLicense server (either running locally on the same machine as your Java application or on another machine that is accessible via TCP/IP), you can avoid using StarLicense.properties altogether by either:
  • Creating an entry named starlic on your DNS server that points to the StarLicense server.
  • Adding an entry starlic in your local hosts file (\Windows\System32\drivers\etc\hosts or /etc/hosts). On Windows, be careful that the hosts file is not renamed to hosts.txt when you edit it with Notepad; this error can be difficult to diagnose if file extensions are hidden.

  However, this method may not be suitable if you are using node-locked licensing or if you need to specify the PRODUCTID (i.e. the type of license requested) - e.g. if you are licensed for StarSQL for iSeries (license code CA). In the latter case, you can specify the productID property on the connection URL rather than in StarLicense.properties e.g.

  jdbc:StarSQL_JDBC://<hostname>:<port>/<database_name>;productID=CA

• Using StarPipes proxy licensing: If the StarSQL for JDBC URL is configured to use a StarPipes Server rather than connecting directly to the DB2 host, the StarPipes Server will obtain licenses on behalf of the StarSQL for JDBC client. The source of the licenses depends on how client licensing on the StarPipes server is configured; the licenses may be obtained from a StarLicense Server or from a node-locked license configured on the StarPipes system. In this scenario, be sure that the DNS server and local hosts file do not resolve the hostname starlic. Alternatively, you can append the property licenseOption=2 to the URL to force the use of StarPipes licensing.