Upgrading a Third-party JDBC Driver Using the CLI

Using the CLI scripts, you can upgrade existing JDBC drivers in the resource template of a runtime node or SystemNode. Executing the CLI scripts updates the driver across the enterprise and also automatically install, sync, and restart the corresponding nodes. The default driver for the resource template is also updated in the ActiveMatrix Administrator database.

Note: This procedure automatically restarts all the nodes on which the JDBC driver version is updated.
    Procedure
  1. Configure the new third-party JDBC driver in TIBCO_HOME using the "Configure Third-Party Driver" wizard of the TIBCO Configuration Tool (TCT).
  2. Verify the updateJDBCDriver target and action in the enterprise_build.xml located in <CONFIG_HOME>\admin\amxadmin\samples\.
    <target name="updateJDBCDriver">
      <AMXAdminTask
       action="updateJDBCDriver"
       objectSelector="Enterprise"
       remote="true"
       propsFile="${instanceProperties}"
       dataFile="${dataFile}" 
       <!--
       options="dryRun"  
       -->
       failOnError="false"/>
     </target>
    Note: You cannot set objectSelector to Environment or Node.
    • remote="true": Upgrades the features for remote nodes. (that is, nodes managed by remote hosts).
    • options="dryRun": If specified, features are not installed or enabled on the node.
    Note: Database operations are not performed when options="dryRun" is used. Hence, any log messages indicating that a feature has been removed or updated can be ignored. The logs are benign.
    For more information on the other attributes, see Using Command-line Interface.
  3. Verify the following data in the enterprise_data.xml located in <CONFIG_HOME>\admin\amxadmin\samples\ and modify OldFeature and NewFeature versions if needed.
    <OldFeature xsi:type="amxdata_base:FeatureID" componentID="com.tibco.tpcl.gen.oracle.jdbc.feature" version="11.2.100.001"/>
    <NewFeature xsi:type="amxdata_base:FeatureID" componentID="com.tibco.tpcl.gen.oracle.jdbc.feature" version="12.1.100.001"/>
    
    
    For example, to upgrade from 12.1.100.001 to 12.2.0.001 modify the entries as below:
    <OldFeature xsi:type="amxdata_base:FeatureID" componentID="com.tibco.tpcl.gen.oracle.jdbc.feature" version="12.1.100.001"/>
    <NewFeature xsi:type="amxdata_base:FeatureID" componentID="com.tibco.tpcl.gen.oracle.jdbc.feature" version="12.2.0.001"/>
  4. Invoke the command-line interface on the build file.

The updateJDBCDriver CLI action was previously done for all nodes in the enterprise. For large number of nodes, this takes long time to complete action for all nodes. Starting with TIBCO ActiveMatrix Hotfix 05, updateJDBCDriver action can be performed for selected hosts or environments in an enterprise. In the updateJDBCDriver target, you can specify a list of hosts or environments to update the JDBC drivers for nodes in the specified hosts or environments. You can specify either host or environment in options, you cannot specify both options at single time. In this feature, the updateJDBCDriver action is performed for specific number of threads at single time to complete the JDBC driver update. This helps to solve database concurrency issue.

Sample <CONFIG_HOME>\admin\amxadmin\samples\enterprise_build.xml:

<target name="updateJDBCDriver">
<AMXAdminTask
action="updateJDBCDriver"
objectSelector="Enterprise"
remote="true"
propsFile="${instanceProperties}
dataFile="${dataFile}"
failOnError="false"
force="true"
options="host={host1,host2,host3,host4,host5,host6}"/>
</target>

 

Note: In the <CONFIG_HOME>\admin\amxadmin\samples\enterprise_data.xml file, <OldFeature> must be specified before <NewFeature>, otherwise, the scripts fail.

Parameters

Starting with TIBCO ActiveMatrix Hotfix 05, following new parameters are provided for updateJDBCDriver target:

Attribute Type Required? Description
options String No The valid options are:
  • host={Host1, Host2, Host3, Host4, Host5, Host6}

    The updateJDBCDriver CLI action is performed only on nodes in the specified hosts from this list.

    Example: options="host={host1,host2,host3,host4,host5,host6}"/>

  • env={Env1, Env2, Env3}

    The updateJDBCDriver CLI action is performed only on nodes in the specified environments from this list.

    If host or environment list is not provided then the action is performed on all nodes in the enterprise.

    Example: options="env={Env1,Env2,Env3}"/>

  • xmlReport, jsonReport

    JSON and XML reports are generated at the end of the action which contains details about action performed and metadata. You need to provide this option to specify whether reports to be generated or not.

    Example: options="xmlReport,jsonReport"/>

  • reportDir

    Reports are generated in the specified location in this option. The default location is sample directory from where the CLI action is performed.

    Example: options="reportDir={C:/reports}"/>

  • timeout

    There is install with resolve mode task in JDBC driver update action. It might take long time to install node with resolve mode which actually restarts the node. You can set this timeout for install with resolve mode task. If timeout is set 5 minutes and node install takes more than that, the thread execution for that node is completed.

    Example: options="timeout=5"/>

    Default: 5 minutes.

force Boolean No If force is set as true, it enables new version even if the old version is not enabled.

If force option is not set, it skips enabling new version on the node if old version is not enabled on node.

Example: force="true"

Default: The force="true" is not present by default, therefore the default value is false.

Sample Output

The following is a sample output of the updateJDBCDriver target:

>ant -f enterprise_build.xml updateJDBCDriver
Buildfile: C:\tibco\v87testInst\data\admin\amxadmin\samples\enterprise_build.xml
updateJDBCDriver:
[AMXAdminTask] 07 Oct 2021 10:04:05 INFO - Initializing JSSE's crypto provider class com.sun.net.ssl.internal.ssl.Provider in default mode
[AMXAdminTask] 07 Oct 2021 10:04:05 INFO - Connecting to AMX Admin server at 'http://na2devasgksh02:8120' as user 'root'.
[AMXAdminTask] 07 Oct 2021 10:04:05 INFO - Executing action 'updateJDBCDriver' for 1 objects from data file 'C:\tibco\v87testInst\data\admin\amxadmin\samples\enterprise_data.xml'
[AMXAdminTask] 07 Oct 2021 10:04:07 INFO - TIBCO-AMX-CLI-000962: Getting entrprise information before executing action 'updateJDBCDriver'
[...]
[AMXAdminTask] 07 Oct 2021 10:05:29 INFO - Starting JDBC driver update for Node: 'env2:node11'
[AMXAdminTask] 07 Oct 2021 10:04:44 INFO - .
[AMXAdminTask] 07 Oct 2021 10:04:42 INFO - .
[AMXAdminTask] 07 Oct 2021 10:04:42 INFO - .
[AMXAdminTask] 07 Oct 2021 10:04:41 INFO - .
[AMXAdminTask] 07 Oct 2021 10:05:30 INFO - Completed JDBC driver update action for Node: 'env2:node8', action completed for '6' out of '19' nodes.
[AMXAdminTask] 07 Oct 2021 10:05:30 INFO - Completed JDBC driver update action for Node: 'env4:node401', action completed for '7' out of '19' nodes.
[AMXAdminTask] 07 Oct 2021 10:05:30 INFO - Completed JDBC driver update action for Node: 'env2:node9', action completed for '9' out of '19' nodes.
[AMXAdminTask] 07 Oct 2021 10:05:30 INFO - Completed JDBC driver update action for Node: 'env2:node10', action completed for '8' out of '19' nodes.
[...]

After completing the updateJDBCDriver action, nodes for which action is completed are displayed in the output.

[AMXAdminTask] 07 Oct 2021 10:08:18 INFO - -------------------------JDBC driver update is successfully done for below nodes------------------------------
[AMXAdminTask] 07 Oct 2021 10:08:18 INFO -
[AMXAdminTask] 07 Oct 2021 10:08:18 INFO - env3:node18, env3:node17, env2:node8, env4:node401, env2:node10
[AMXAdminTask] 07 Oct 2021 10:08:18 INFO - env2:node9, env2:node11, env2:node12, env3:node13, env1:node2
[AMXAdminTask] 07 Oct 2021 10:08:18 INFO - env1:node4, env2:node7
[AMXAdminTask] 07 Oct 2021 10:08:18 INFO -
[AMXAdminTask] 07 Oct 2021 10:08:18 INFO - -------------------------JDBC driver update interrupted due to timeout for below nodes------------------------------
[AMXAdminTask] 07 Oct 2021 10:08:18 INFO -
[AMXAdminTask] 07 Oct 2021 10:08:18 INFO - env1:node6, env1:node3, env1:node5, env1:node1
[AMXAdminTask] 07 Oct 2021 10:08:18 INFO -
[AMXAdminTask] 07 Oct 2021 10:08:19 INFO - ################################################################# root_JDBCDriverUpdate_20211007100408 #################################################################
[AMXAdminTask] 07 Oct 2021 10:08:19 INFO -
[AMXAdminTask] 07 Oct 2021 10:08:19 INFO - Publishing DBC Driver Update report to the [XML format] file: C:\reports\JDBCDriverUpdateReport_root_JDBCDriverUpdate_20211007100408.xml
[AMXAdminTask] 07 Oct 2021 10:08:20 INFO - JDBC Driver Update report file was created successfully.
[AMXAdminTask] 07 Oct 2021 10:08:22 INFO - Publishing JDBC Driver Update report to the [JSON format] file: C:\reports\JDBCDriverUpdateReport_root_JDBCDriverUpdate_20211007100408.json
[AMXAdminTask] 07 Oct 2021 10:08:22 INFO - JDBC Driver Updatereport file was created successfully.
[AMXAdminTask] 07 Oct 2021 10:08:22 INFO - Action finished at 10/7/21 10:08 AM in 255.9 seconds

BUILD SUCCESSFUL
Total time: 4 minutes 22 seconds