Skip to content

Commit

Permalink
Merge pull request #3352 from zowe/anax-v2.13-odbctroubleshoot-cli
Browse files Browse the repository at this point in the history 
Anax v2.13 odbctroubleshoot cli
  • Loading branch information
@anaxceron
anaxceron authored Jan 12, 2024
2 parents 30ed75d + 87911e0 commit 00f7106
Show file tree
Hide file tree
Showing 3 changed files with 152 additions and 34 deletions.
98 changes: 98 additions & 0 deletions docs/troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# IBM Db2 Database Plug-in troubleshooting

As part of the IBM Db2 Database Plug-in installation, the ODBC driver is automatically installed. The driver is required to connect to Db2, but installation can fail due to security restrictions.

When the ODBC driver installation fails, Zowe CLI displays an error message. To resolve this, the user can manually download and install the driver.

**Symptom:**

The ODBC driver installation fails when installing the IBM Db2 Database Plug-in.

**Sample:**

The ODBC driver installation can fail due to several factors, displaying the following error when the `zowe plugins install` command is issued:

```
_______________________________________________________________
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
```

To identify the cause of the error and get more details to troubleshoot, run the following command:

```
npm install ibm_db --foreground-scripts true
```

The response includes an error message, which could specify a timeout or unpacking error.

#### Timeout error

Network restrictions can prevent the ODBC driver from downloading, resulting in a timeout error:

```
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.
=====================================
```

To troubleshoot a timeout error, see [Downloading the ODBC driver manually](#downloading-the-odbc-driver-manually).

#### Unpacking error

If the driver downloads successfully, security settings can still prompt an unpacking error.

In the following example, the ODBC driver was downloaded manually and the environment variable `IBM_DB_INSTALLER_URL` was set.

```
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
```

To troubleshoot a packaging error, see [Fixing a failed extraction](#fixing-a-failed-extraction).

**Solution:**

#### Downloading the ODBC driver manually

To manually download the ODBC driver, see instructions in [Downloading the ODBC driver](../../user-guide/cli-db2plugin.md#downloading-the-odbc-driver).

#### Fixing a failed extraction

1. Manually extract the ODBC driver binaries from the `build.zip` file which is bundled with the [ibm_db](https://www.npmjs.com/package/ibm_db) package. The `build.zip` archive can also be downloaded from [GitHub](https://github.com/ibmdb/node-ibm_db/blob/master/build.zip).

2. Open the `build/Release` folder and copy the binary for your Node version (for example, `odbc_bindings.node.18.18.2` if you have Node 18) into the Db2 plug-in folder (`C:\Users\username\.zowe\plugins\installed\node_modules\@zowe\db2-for-zowe-cli\node_modules\ibm_db\build\Release`).

3. Rename the file to `odbc_bindings.node`. This is the name used by the Db2 plug-in.

You have successfully extracted the ODBC driver.

:::note

The preceding steps extract the driver binary to fix a broken installation of the IBM Db2 Database Plug-in. When installing a new version of the plug-in, perform the workaround again to fix a failed extraction.

:::
79 changes: 46 additions & 33 deletions docs/user-guide/cli-db2plugin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,7 @@ Follow these procedures if you downloaded the Zowe installation package:
#### Downloading the ODBC driver
Download the ODBC driver before you install the Db2 plug-in.
**Follow these steps:**
Download the ODBC driver before you install the Db2 plug-in:
1. If you are installing the plug-in on a Apple computer that contains an M1 (or later architecture) processor, complete the steps in [M1 processor installation](../user-guide/cli-db2-install-m1.md). If not, continue to Step 2.
Expand All @@ -64,13 +62,15 @@ Download the ODBC driver before you install the Db2 plug-in.
4. Place the ODBC driver in the `odbc_cli` folder. **Do not extract the ODBC driver**.
You downloaded and prepared to use the ODBC driver successfully. Proceed to install the plug-in to Zowe CLI.
You downloaded and prepared to use the ODBC driver successfully. Proceed to install the plug-in to Zowe CLI.
#### Installing Xcode on MacOS
To install the Db2 CLI plug-in on MacOS, you need the command line tools, which can be obtained by installing Xcode from the [App Store](https://medium.com/r/?url=https%3A%2F%2Fapps.apple.com%2Fus%2Fapp%2Fxcode%2Fid497799835%3Fmt%3D12).
**Note:** On some versions of MacOS, you may receive the error `xcrun: error: invalid active developer path` as shown below:
:::note
On some versions of MacOS, you may receive the error `xcrun: error: invalid active developer path` as shown below:
```
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
Expand All @@ -82,17 +82,15 @@ If this occurs, a manual refresh of the command line tools is required by runnin
sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install
```
:::
#### Installing the plug-in
Now that the Db2 ODBC CLI driver is downloaded, set the `IBM_DB_INSTALLER_URL` environment variable and install the Db2 plug-in to Zowe CLI.
**Follow these steps:**
With the Db2 ODBC CLI driver downloaded, set the `IBM_DB_INSTALLER_URL` environment variable and install the Db2 plug-in to Zowe CLI:
1. Open a command line window and change the directory to the location where you extracted the `zowe-cli-bundle.zip` file. If you do not have the `zowe-cli-bundle.zip` file, see the topic **Install Zowe CLI from local package** in [Installing Zowe CLI](cli-installcli.md) for information about how to obtain and extract it.
2. From a command line window, set the `IBM_DB_INSTALLER_URL` environment variable by issuing the following command:
2. From a command line window, set the `IBM_DB_INSTALLER_URL` environment variable:
- Windows operating systems:
Expand All @@ -105,22 +103,25 @@ Now that the Db2 ODBC CLI driver is downloaded, set the `IBM_DB_INSTALLER_URL` e
export IBM_DB_INSTALLER_URL=<path_to_your_odbc_folder>/odbc_cli
```
For example, if you downloaded the Windows x64 driver (ntx64_odbc_cli.zip) to C:\odbc_cli, you would issue the following command:
```
set IBM_DB_INSTALLER_URL=C:\odbc_cli
```
For example, if you downloaded the Windows x64 driver (`ntx64_odbc_cli.zip`) to `C:\odbc_cli`:
2. Issue the following command to install the plug-in:
```
set IBM_DB_INSTALLER_URL=C:\odbc_cli
```
3. To install the IBM Db2 Database Plug-in:
```
zowe plugins install db2-for-zowe-cli.tgz
```
3. [Address the license requirements](#addressing-the-license-requirement) to begin using the plug-in.
4. [Address the license requirements](#addressing-the-license-requirement) to begin using the plug-in.
You have installed the IBM Db2 Database Plug-in successfully.
## Addressing the license requirement
To successfully connect the Db2 CLI plug-in to a database on z/OS, a license needs to be present either on the client where the Zowe CLI is executed from, or else on z/OS. If you do not have a license configured when you execute Db2 CLI commands, you will receive an error `SQL1598N`, for example:
To successfully connect the Db2 CLI plug-in to a database on z/OS, a license needs to be present either on the client where the Zowe CLI is executed from, or else on z/OS. If you do not have a license configured when you execute Db2 CLI commands, you will receive an error `SQL1598N`:
```
DB2 ODBC Driver Error: [node-ibm_db] SQL_ERROR
Expand All @@ -138,16 +139,24 @@ If the utility `db2connectactivate` has not been executed against the Db2 databa
1. Locate your client copy of the Db2 license file `db2consv_zs.lic`.
**Note:** The license must be of version 11.5 if the Db2 server is not `db2connectactivated`. You can buy a db2connect license from IBM. The connectivity can be enabled either on server using db2connectactivate utility or on client using client side license file.
:::note
The license must be of version 11.5 if the Db2 server is not `db2connectactivated`. You can buy a db2connect license from IBM. The connectivity can be enabled either on server using db2connectactivate utility or on client using client side license file.
To know more about DB2 license and purchasing cost, please contact IBM Customer Support.
:::
2. Copy your Db2 license file `db2consv_za.lic` and place it in the following directory.
```
<zowe_home>/plugins/installed/lib/node_modules/@zowe/db2-for-zowe-cli/node_modules/ibm_db/installer/clidriver/license
```
**Tip:** By default, <zowe_home> is set to `~/.zowe` on \*UNIX Aand Mac systems, and `C:\Users\<Your_User>\.zowe` on Windows systems.
:::tip
After the license is copied, you can use the Db2 plugin functionality.
By default, <zowe_home> is set to `~/.zowe` on \UNIX and Mac systems, and `C:\Users\<Your_User>\.zowe` on Windows systems.
:::
After the license is copied, you can use the Db2 plug-in functionality.
## Creating a user profile
Expand All @@ -163,13 +172,17 @@ We recommend that you create profiles using the configuration file. We do not re
When you issue various `zowe config` commands, such as `init`, `auto-init`, and `convert-profiles`, they create a `zowe.config.json` configuration file. When you install the DB2 plug-in, the commands create an entry for a `db2 profile` in your `zowe.config.json` file.
Alternatively, you can create a db2 profile manually by adding a section that contains the configuration details to your `zowe.config.json` configuration file.
Alternatively, you can create a db2 profile manually by adding a section that contains the configuration details to your `zowe.config.json` configuration file:
1. Browse to the following directory: `C:\Users\<username>\.zowe`
2. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ.
**NOTE:** If the file does not exist, issue the following command to create the configuration file: `zowe config init --gc`
:::note
If the file does not exist, issue the following command to create the configuration file: `zowe config init --gc`
:::
3. Add code to the "profiles" section as shown in the following example:
```
Expand All @@ -187,47 +200,47 @@ Alternatively, you can create a db2 profile manually by adding a section that co
}
```
4. Save the file
4. Save the file.
You can now use your profile when you issue commands in the db2 command group.
You can now use your profile when you issue commands in the db2 command group.
### Creating plug-in profiles using a command
The following steps describe how to create a profile using the `zowe profiles create` command.
Create a profile using the `zowe profiles create` command:
1. Open a terminal window and issue the following command:
```
zowe profiles create db2 <profile_name> –-host <host> --port <port> --user <user> --password <password> --region-name <region>
```
**`profile_name`:**
**`profile_name`**
Specifies a name for your profile.
**`host`:**
**`host`**
Specifies the host name for the instance.
**`user`:**
**`user`**
Specifies your user name to log in to the instance.
**`password`:**
**`password`**
Specifies your password to log in to the instance.
**`port`:**
**`port`**
Specifies the port number to connect to the instance.
**`database`:**
**`database`**
Specifies the database to use on the instance.
**Example:**
```
zowe profiles create db2-profile database1 --host db2.zowe.org --port 25000 --user zowe --password zowepass --database zowedb
```
2. Press Enter. The result of the command displays as a success or failure message.
2. Press `Enter`. The result of the command displays as a success or failure message.
You can now use your profile when you issue commands in the db2 command group.
You can now use your profile when you issue commands in the db2 command group.
9 changes: 8 additions & 1 deletion sidebars.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -769,7 +769,14 @@ module.exports = {
"troubleshoot/cli/troubleshoot-cli-credentials",
"troubleshoot/cli/known-cli",
"troubleshoot/cli/cli-issue",
"troubleshoot/cli/troubleshoot-cli-plugins",
],
},
{
type: "category",
label: "Troubleshooting Zowe CLI plug-ins",
link: {type:"doc", id:"troubleshoot/cli/troubleshoot-cli-plugins"},
items: [
"troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in",
],
},
{
Expand Down

0 comments on commit 00f7106

Please sign in to comment.