Document installing DB2 plug-in for customers unable to extract the ODBC driver

[t1m0thyj]

Is your request for enhancement related to a problem? Please describe.

During the installation process of the DB2 plug-in for Zowe CLI, it attempts to automatically install the ODBC driver which is required to connect to DB2. If this fails, I may see an error like the following and there is no documentation telling me what to do:

npm ERR! code 1
npm ERR! path C:\Users\User\node_modules\ibm_db
npm ERR! command failed
npm ERR! command C:\WINDOWS\system32\cmd.exe /d /s /c node installer/driverInstall.js

Describe the solution you'd like

Document the workaround for this error (thanks to @sosadchuk):

• Manually extract the ODBC driver binary from the "build.zip" file which is bundled with the ibm_db package or can alternatively be downloaded from GitHub.
• Copy the binary for your OS and Node version (e.g., "odbc_bindings.node.18.18.2") into the DB2 plug-in folder ($HOME\.zowe\plugins\installed\node_modules\@zowe\db2-for-zowe-cli\node_modules\ibm_db\build\Release).
• Rename the file to "odbc_bindings.node". (This is the name expected by the DB2 plug-in.)

Related doc pages

https://docs.zowe.org/stable/user-guide/cli-db2plugin#downloading-the-odbc-driver

Additional context

This workaround applies to customers who are unable to extract the ODBC driver, even after a successful download.

[sosadchuk]

Hi guys, wanted to add some details.

On db2 plugin installation users will probably see just the following generic message:

_______________________________________________________________
Installed plugin name = '@zowe/db2-for-zowe-cli'

_____ Validation results for plugin '@zowe/db2-for-zowe-cli' _____

*** CmdError: Failed to combine command definitions. Reason = Encountered an error loading one of the files (cli/call/Call.definition.js) that matched the provided command module glob for the glob **/cli/*/*.definition!(.d).*s: Could not locate the bindings file. Tried:
 → C:\Users\username\.zowe\plugins\installed\node_modules\@zowe\db2-for-zowe-cli\node_modules\ibm_db\build\odbc_bindings.node
 → C:\Users\username\.zowe\plugins\installed\node_modules\@zowe\db2-for-zowe-cli\node_modules\ibm_db\build\Debug\odbc_bindings.node
 → C:\Users\username\.zowe\plugins\installed\node_modules\@zowe\db2-for-zowe-cli\node_modules\ibm_db\build\Release\odbc_bindings.node
 ...

Then it might be a good idea to check whether ibm_db package installed correctly. The following message might be an indicator that odbc driver installation is blocked by organization security (failure visible only with --foreground-scripts true):

npm i ibm_db --foreground-scripts true
[#################.] | reify:lodash: timing reifyNode:node_modules/axios Completed in 2204ms
> [email protected] install
> node installer/driverInstall.js

platform = win32, arch = x64, node.js version = v18.14.2http://hostname.com/artifactory/api/npm/npmjs/ibm_db/-/ibm_db-3.2.3.tgz 7210ms (cache miss)
[##################] - reify:ibm_db: http fetch GET 200 http://hostname.com/artifactory/api/npm/npmjs/ibm_db/-/ibm_db-3.2.3.tgz 7210ms (cache miss)
****************************************
You are downloading a package which includes the Node.js module for IBM DB2/Informix.  The module is licensed under the Apache License 2.0. The package also includes IBM ODBC and CLI Driver from IBM, which is automatically downloaded as the node module is installed on your system/device. The license agreement to the IBM ODBC and CLI Driver is available in C:\Users\username\node_modules\ibm_db\installer\clidriver. Check for additional dependencies, which may come with their own license agreement(s). Your use of the components of the package 
and dependencies constitutes your acceptance of their respective license agreements. If you do not accept the terms of any license agreement(s), then delete the relevant component(s) from your device.
****************************************

Downloading DB2 ODBC CLI Driver from https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli/ntx64_odbc_cli.zip ...

ETIMEDOUT : https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli/ntx64_odbc_cli.zipbm_db/-/ibm_db-3.2.3.tgz 7210ms (cache miss)
Downloading DB2 ODBC CLI Driver from https://github.com/ibmdb/db2drivers/raw/main/clidriver/ntx64_odbc_cli.zip ...

ETIMEDOUT : https://github.com/ibmdb/db2drivers/raw/main/clidriver/ntx64_odbc_cli.zipifactory/api/npm/npmjs/ibm_db/-/ibm_db-3.2.3.tgz 7210ms (cache miss)

=====================================
Error: Installation of ibm_db failed.
=====================================


added 10 packages, and audited 115 packages in 1m

Then user can try installing the driver manually. After downloading ODBC archive and setting the IBM_DB_INSTALLER_URL=, you can get the following error that might indicate an unpacking error caused by security settings (can be verified by attempting to etract zip arhive manually - will get Data error):

npm install ibm_db --foreground-scripts true
[#################.] | reify:axios: timing reify:audit Completed in 938ms
> [email protected] install
> node installer/driverInstall.js

platform = win32, arch = x64, node.js version = v16.13.0de_modules/axios Completed in 1308ms
[##################] / reify:ibm_db: timing reifyNode:node_modules/axios Completed in 1308ms
****************************************
You are downloading a package which includes the Node.js module for IBM DB2/Informix.  The module is licensed under the Apache License 2.0. The package also includes IBM ODBC and CLI Driver from IBM, which is automatically downloaded as the node module is installed on your system/device. The license agreement to the IBM ODBC and CLI Driver is available in C:\Users\username\node_modules\ibm_db\installer\clidriver. Check for additional dependencies, which may come with their own license agreement(s). Your use of the components of the package and dependencies constitutes your acceptance of their respective license agreements. If you do not accept the terms of any license agreement(s), then delete the relevant component(s) from your device.
****************************************

Downloading DB2 ODBC CLI Driver from C:/Users/username/odbc_cli/ntx64_odbc_cli.zip ...

node:events:368####] / reify:ibm_db: timing reifyNode:node_modules/axios Completed in 1308ms
      throw er; // Unhandled 'error' event
      ^

Error: invalid distance too far back
    at Zlib.zlibOnError [as onerror] (node:zlib:190:17)
Emitted 'error' event on InflateRaw instance at:
    at emitErrorNT (node:internal/streams/destroy:157:8)
    at emitErrorCloseNT (node:internal/streams/destroy:122:3)
    at processTicksAndRejections (node:internal/process/task_queues:83:21) {
  errno: -3,
  code: 'Z_DATA_ERROR'
}
npm ERR! code 1
npm ERR! path C:\Users\username\node_modules\ibm_db
npm ERR! command failed
npm ERR! command C:\WINDOWS\system32\cmd.exe /d /s /c node installer/driverInstall.js

Then it makes sense to proceed with reusing already prepared bindings like Timothy described.
That will solve the bindings issue, and I guess the ibm_db package comes with precompiled driver for Win that will do the work.

Thanks,
Sergei.

[anaxceron]

@sosadchuk -- working on documenting troubleshooting steps for this issue. you can see the documentation here:
#3352