Managing analysis projects

Scan and manage analysis projects by using the Z Understand container.

1. Create a project
   1. Navigate to the Z Understand container folder in the Terminal by running the following command:

      cd /opt/bobz-understand

   2. Optional: Run the cli.sh script without any parameters or with the --help parameter to see all the possible project-related actions and their syntax.

      Usage:
      ./cli.sh [Operation] [Arguments] <project_name>
      Operation (mutually exclusive):
          -a                                                           attach to the container
          -encrypt <password>                                          encrypt a password for use in configuration files
          -c [ --create ] arg                                          create project, where <arg> is a project configuration file name located in the 'config/projects' folder
          -d [ --delete ]                                              delete project
          --delete-forced                                              force delete project in case of read locks
          -r [ --rename ] arg                                          rename project <project_name> where <arg> is the new name of the project
          -b [ --build ]                                               build the project
          -m [ --make ]                                                make the project
          --sync                                                       sync project with zOS using sync configuration from dashboard
          -s [ --build-sel ]                                           build selection on the project
          -B [ --build-batch ]                                         arg build project in batches, where <arg> is batch_size
          -u [ --upgrade ]                                             project repository upgrade
          --list-props                                                 list all the current project properties
          --update-API-res                                             update the extensibility API resolutions
          --log-level arg                                              specify a log level: D,I,W,E (Debug, Info, Warning, Error), used in conjunction with another option
          --list-projects                                              list all the existing projects
          -doc -api-key <api_key>                                      run the Doc Generation tool for the whole project,
               -username <username>                                        add -language <locale> (options include: en, ja, es, fr, pt, de, kr, nl)
                                                                                  to set the language of documentation output,
                                                                           use -doc -resume to continue if the generation process times out,
                                                                           username (required only for CPD environment),
          -doc -delete                                                 run the Doc Generation tool to delete the generated documentation
          -zos --agent-tc arg                                          test connection with the zOS connection, where <arg> is the name of the zOS connection (no <project_name> required)
          -zos --attach-zos arg                                        attach a zOS connection to the project, where <arg> is the name of the zOS connection
          -zos --scan-PDS arg                                          scan a PDS library, where <arg> is the name of the zOS connection followed by the list of PDS libraries
          -zos --get-members arg                                       get members from libraries, where <arg> is the name of the zOS connection followed by the list of library names
          -dd -p <project_name> -bob-api-key <api_key>                run the Data Dictionary Generation tool for the whole project
               [-lang <language>]                                          where <language> is cobol, pl1, or pli (default: cobol)
               [-m <mode>]                                                 migration mode (optional, use only for migration)
               [-w <workers>]                                              number of workers (optional, default: 4)
      <project_name>                      required, name of the project
      Examples:
          1) to create a project: ./cli.sh -c COBOL.ini Proj1
          2) to build a project:  ./cli.sh -b Proj1
          3) to delete a project: ./cli.sh -d Proj1
          4) to rename a project: ./cli.sh -r NewProjName Proj1
          5) to upgrade a project repository: ./cli.sh -u Proj1
          9) to run Doc Generation: ./cli.sh -doc -api-key YOUR_KEY MyProject
          10) to sync project with zOS: ./cli.sh --sync Proj1
          11) to generate data dictionary: ./cli.sh -dd -bob-api-key YOUR_KEY -p MyProject
          12) to generate data dictionary with language: ./cli.sh -dd -bob-api-key YOUR_KEY -lang pl1 -p MyProject
          13) to generate data dictionary for migration: ./cli.sh -dd -bob-api-key YOUR_KEY -m migration -w 8 -p MyProject

   3. Prepare the configuration file for the project creation. A list of sample files is provided in the config/projects/samples folder. Open the folder and list the available sample files by running the following command:

      cd config/projects/
      ls samples

   4. Clone the sample file that corresponds to the type of relational database server that you configured. For more information, see 3.e in the configuration instructions.
      For example, clone the sample file for Microsoft SQL Server by entering the following command:

      cp samples/new_proj_sql.ini .

   5. Open the cloned sample file by running the following command:

      vi new_proj_sql.ini

   6. Modify the file as follows:
      1. Press the i key on the keyboard to enable keyboard input in the editor.
      2. Replace the line comments, which represent the properties in the file, with actual values.

      Note: If you are creating an analysis project from a migrated Windows project.
   7. Press the Escape key on the keyboard to exit insert mode. Then, save the file to disk and exit the editor by typing :wq and pressing the Enter key.
   8. Create a project by running the following command:

      cd ..
      ./cli.sh -c new_proj_sql.ini <PROJECT_NAME>

   A project folder is created under the projects/<PROJECT_NAME> folder.
2. Add files to the project

   Creating the project also creates a specific folder structure that is named and organized by object type. Add the source files to be analyzed to the appropriate project folders. The list of project folders can differ according to the chosen settings during the project creation.

3. Adjust configuration settings (optional)
   If Building Decisions are required, then add the decisions to the project settings. If required, add the compilation variables used in Conditional compilation directives in Cobol which are not defined in the COBOL sources.
4. Scan the project
   To do so, run the following command:

   ./cli.sh -b <PROJECT_NAME>

   The progress of the operation is displayed in the Terminal.

   Note:

   If a PL/I program references a copybook that is unavailable, the program will not be scanned, and consequently, no data will be recorded in the repository.

5. Index the source code of the new project to improve the AI Chat answers. To do so, run the indexing commands from the Terminal. These commands are required for a Cloud Pak for Data (CPD) environment. Two types of indexing commands are available:
   1. The semantic indexing, which uses AI to generate explanations for every paragraph in the application. Run the semantic indexing for a new project or if the source code of a project has changed.
      To run the semantic indexer, enter the following command:

      ./cli.sh -si -api-key <API_KEY> <PROJECT_NAME>

      You can use the explain parameter to improve the quality of the explanations. With this parameter, the semantic indexer generates explanations for the source code by using the AI model and indexes the explanations. This index has better quality for the purpose of retrieval. However, indexing takes more time as the explanations are generated first. If you want to use this parameter, enter the following command:

      ./cli.sh -si -m explain -api-key <API_KEY> <PROJECT_NAME>

      You can use the mode parameter to reduce the indexing time. With this parameter, the semantic indexer indexes the code itself without involving the AI model. If you want to use this parameter, enter the following command:

      ./cli.sh -si -m code -api-key <API_KEY> <PROJECT_NAME>

   2. The business rules indexing, which indexes the stored business rules. Run it for a new project or if business rules have been added to a project.
      To index the business rules, enter the following command:

      ./cli.sh -si-brd -api-key <API_KEY> <PROJECT_NAME>

   Note: In all the commands, <API_KEY> is an cloud API key.
6. Optional: Run the Doc generation tool to automatically create accurate, easy-to-navigate program and application documentation.