Troubleshooting and support

This section discusses troubleshooting, know issues and limitations of IBM Bob Premium Package for Z.

Large program considerations

When you are working with large programs, you might need to increase the value of the Memory Allocation setting.

Since the exact size of large programs cannot be determined, the memory allocation value required for your programs cannot be predetermined. If your dialogue with Bob chat stops abruptly during the scan_program tool execution, or if you observe files in your workspace with names that begin with core, heapdump, javacore and Snap, then it is recommended to increase the Memory Allocation value.

Perform the following steps to modify the Memory Allocation value:

On the Extensions tab, right-click on the IBM Z Open Editor extension and select Settings.
On the Settings tab, select User and search for the Memory Allocation parameter.
The default value set by this package for Memory Allocation is 1024. It is recommended to set the value to 2048 if an increase is needed.

Collecting diagnostics

To collect diagnostics in IBM® Bob Premium Package for Z, perform the following steps:

Set the Log Level setting for the IBM Bob Premium Package for Z extension to debug. To find Settings, select the gear icon (Manage) on the extension page and then select Settings.
Run the scenario that exhibits the issue needing diagnosis.
Download the task file (task that is being investigated) to your workspace so that it can be collected along with other diagnostic files.
Click the task name to expand it, and then click the Export task history icon. Save the task file to your currently open IBM Bob workspace.
Click IBM Bob > Command Palette… and select IBM Bob for Z: Collect diagnostics.
A message appears with the zip file location (current workspace). You can provide this zip file with any problem report submitted.

Limitations of bulk data dictionary

Bulk data dictionary processing is currently supported only for programs with 1,000 lines or fewer.
The maximum size of the bulk payload stored in the database is 2 MB.

Workspace file organization requirements

Files included by the source program can reside anywhere within the workspace. However, certain files must be placed in designated directories or use specific file extensions to ensure they are correctly discovered by the tools.

COBOL

Program copybook files can be in any workspace directory. If you need place to store system copybook files, you can put them in <workspace>/copybooks and they will be found.
Ensure that the copybook file extensions are any of the ones defined in Z Open Editor settings for Cobol: Include File Extensions. You can add additional file extensions there as well.

IMS

Place PSB files in: <workspace>/PSB/
Place DBD files in: <workspace>/DBD/
Place TRAN files in: <workspace>/TRAN/

PL/I

Program include files can be in any workspace directory. If you need place to store system include files, you can put them in <workspace>/includes and they will be found.
Ensure that the include file extensions are any of the ones defined in Z Open Editor settings for Pl1: Include File Extensions. You can add additional file extensions there as well.

Request failure during documentation generation for large programs

When generating documentation for large source files (for example, programs exceeding 2,000 lines of code), you might encounter the following error:

ERROR    [4/4] E300 - Bob Shell request failed: [Errno 7] Argument list too long: 'bob'. Will try again.
ERROR - zdocgen - E501 - Document generation cannot proceed. All connection attempts to the LLM failed

Resolution

To reduce the amount of code processed per request, configure a maximum line threshold for documentation generation inside the container.

Navigate to the Understand container installation directory. For example:
```
cd /root/container/bobz-understand
```
Open an interactive session inside the container:
```
./cli.sh -a
```
Navigate to the documentation generation directory:
```
cd 'IBM Doc Generation'
```
Create a .env file and set the environment variable APP_MAX_LINES_OF_CODE_THRESHOLD to a value less than 2100:
```
echo APP_MAX_LINES_OF_CODE_THRESHOLD=2100 > .env
```
Exit the container session.

Note: If the issue persists after reducing the threshold, exclude extremely large programs or source files (for example, files larger than 40,000 lines of code) from documentation generation.

Model is busy during documentation generation

When generating documentation using Bob shell-based Z Understand Linux container, the model might become unresponsive. If a request times out, the system automatically retries up to four times. If all four attempts fail, then the process stops.

When this occurs the following messages are found in the log file:

ERROR - zdocgen - [4/4] E300 - Bob Shell request failed. Will try again.
ERROR - zdocgen - E501 - Document generation cannot proceed. All connection attempts to the LLM failed

Feedback and issues

Use IBM Bob - IBM Community to share your feedback and report issues on IBM Bob Premium Package for Z.