Skip to content
BluAge Documentation

Copybooks Management

Copybooks usually represent a significant portion of your COBOL project inputs. This page will help you through the process of optimizing their modernization.

Copybook Inclusion

When creating a new COBOL project (see here), you can choose the behavior regarding how to handle copybooks in your Bluage Reverse project.

The behavior is managed by the Physically inline copybooks into programs checkbox as shown below :

CopybooksManagement1

NOTE : A Knowledge Base Project is mandatory to use the physical inlining behavior when creating your COBOL project. You can either create one previous to creating your COBOL project or let the COBOL creation wizard warn you that no Knowledge Base Project has been found and follow the instructions in order to create one on-the-fly. For more information about the creation and usage of a BluAge Knowledge Base project, please refer to the Knowledge Base project page.

Logical Inlining (deprecated)

If you disable this option, copybook files will be logically inlined into your COBOL files. This means that the textual content of your COBOL files won't be modified. However, when opening the file using the BluAge COBOL editor or the BluAge COBOL annotations editor, the content of each copybook will be inlined on-the-fly before displaying.

Here is an example :

CopybooksManagement2

Left editor part is the textual content of a COBOL file named custAUDT.cblmf. We can see the COPY statement not being processed, and the file not modified. Right editor part is the same file opened with the BluAge COBOL annotations editor. Here we can see that the COPY statement has been commented and the textual content of the copybook custAUDT.cpy has been inlined after.

NOTE : This behavior is deprecated and only used for compatibility purpose. We strongly suggest that you use the physical inlining behavior for your new COBOL project or the Logical To Physical Inlining Migration tool, explained below, for your already created COBOL project. Moreover, copybooks management wizards explained in the following sections are not compatible with logical inlining.

Physical Inlining

Introduction

If you keep this option enabled, copybook files will be physically inlined into your COBOL files. This means that the textual content of your COBOL files will be modified to copy/paste the content of each copybook after each COPY statement. The statement itself will be commented. Thus, the content displayed by the BluAge COBOL editor and the BluAge COBOL annotations editor are exactly the same as the textual content of the copybook itself.

Using the same example as before, here is the outcome of this behavior when creating your COBOL project :

CopybooksManagement3

Left editor part is the textual content of the custAUDT.cblmf file, where the content has been modified to match the output displayed in the BluAge COBOL editor and the BluAge COBOL annotations editor editors (right editor part).

COBOL Copybook Annotations

In order to keep information about the inlining, BluAge annotations are automatically created for each COPY statement, which wrap the content of the copybook in the COBOL file, as shown below :

CopybooksManagement4

The name of the copybook is displayed on the message of the COBOL - Copybook annotations, and more information are provided in the Eclipse Properties view when you left-click on the annotation, especially the project relative path of the copybook file.

CopybooksManagement5

You can access the source copybook file by right-clicking on your COBOL - Copybook annotation and selecting the Go To Copybook entry :

CopybooksManagement6 CopybooksManagement7

NOTE : For more information about BluAge Annotations, please refer to the BluAge Annotations page.

Logical To Physical Inlining Migration

For existing COBOL projects using the logical inlining behavior, a migration is possible to rewrite your project to match the physical one. It will modify your textual COBOL files and create the annotations the same way as the COBOL creation wizard.

You can access this migration by right-clicking on your COBOL project, then select the Physically Inline Copybooks Into Programs entry in the COBOL Tools menu.

CopybooksManagement8

Here is the before/after result of the migration on the custAUDT.cblmf file :

CopybooksManagement9

NOTE : Make sure all your editors are closed and your workspace built before using this tool.

Effects On Statistics

COBOL - Copybook annotations are used as a marker to provide information for copybook management, and not as a marker of advancement in the modernization process. As such, these annotations are ignored by the Statistics View and are not taken into account in statistics exports such as XLS and HTML.

CopybooksManagement10

NOTE : For more information about BluAge Statistics, please refer to the BluAge Annotations page.

Effects On Annotations Migration

When creating a new COBOL project using physical inlining, copybook annotations will be provided from the beginning by the initial inining. As such, when using the Annotations Migration Tool to transfer annotations from previous projects into the newly created one, copybook annotations will not be migrated.

NOTE : For more information about the BluAge Annotations Migration Tool, please refer to the BluAge Annotations page.

Unused Copybooks Wizard

Your COBOL project may have been created with unnecessary copybooks that are not included in any COBOL file. Their presence can lead to extra useless work during the modernization part, so it can be important to track them down in order to exclude them from processing by deleting them.

You can access such a tool by right-clicking on your COBOL project and selecting the Find Unused Copybooks entry in the COBOL Tools menu.

CopybooksManagement11

After processing, the following wizard appears :

CopybooksManagement12

The tree view allows you to browse through all unused copybooks that have been found in your COBOL project. By default, all unused copybooks are selected for deletion. Once you are ready, you can click on the Finish button, which will delete all selected files.

Copybook Usages Wizard

On the other end, it can be useful to know all the usages of a given copybook file. You can access such a tool by right-clicking on your copybook file and selecting the Find Copybook Usages entry in the COBOL Tools menu.

CopybooksManagement11

After processing, the following wizard appears :

CopybooksManagement14

The tree view allows you to browse through all inclusions of this copybook. You can double-click on any COBOL file to open it, or on any annotation to select it in an editor.

CopybooksManagement15

Once you are done, you can click on Done to close this wizard.

Copybook Annotations Synchronization

Copybook files are used to carry centralized information, and this behavior must be taken into account in the modernization process in order to prevent multiple modernizations of the same copybook file in different COBOL files.

Once the content of a copybook file has been modernized, you may want to propagate the modernization information, ie the modernization annotations applied to the copybook content, through all places in the COBOL project where the same copybook content has been inlined.

You can achieve this synchronization from multiple places :

  1. From a copybook file, to propagate its annotations through all COBOL files of the project;
  2. From an annotation in a COBOL file, to use these annotations as reference to update the copybook annotations, then propagate them through all COBOL files of the project;
  3. From a COBOL file, to use the annotations of each COBOL - copybook annotation as reference to update their associated copybooks annotations, then propagate them through all COBOL files of the project;

NOTE : The place you choose to start the synchronization process is extremely important because it will define the reference for all other inclusions. This means that any annotation that does not match one in your reference copybook/annotation/COBOL file will be deleted by the process.

Synchronization from a copybook file

You can propagate the annotations of a copybook file through all COBOL files in your project by right-clicking on your copybook file and selecting the Synchronize Annotations entry of the COBOL Tools menu.

CopybooksManagement16

Here is a practical example of annotation propagation :

  • Let's say the content of the custAUDT.cpy copybook file has to be skipped in the COBOL project. Start by applying a Skipped annotation to the content of the copybook file using the Annotations Text Editor.

CopybooksManagement17

  • Then, you may want to propagate this information through all COBOL files in the COBOL project where this copybook is referenced. Select the Synchronize Annotations entry of the COBOL Tools menu as shown above. The annotation synchronization is launched. Once the process has been completed, the following wizard appears to provide the results of the operation :

    CopybooksManagement18

  • Here you can see that 4 Skipped annotations have been added on the 4 locations where the custAUDT.cpy is referenced in the project. You can double-click on any COBOL file to open it, or on any annotation to select it in an editor.

    CopybooksManagement19

  • You can click on the Done button to close the wizard when you are okay with the results.

Now let's say that the annotation is not the one you wanted in the first place. Since the process of propagation is strict, you can delete the Skipped annotation in your copybook file then use the same steps to propagate the deletion :

CopybooksManagement20 CopybooksManagement21

Here you can see that the 4 Skipped annotations previously added have been deleted on the 4 locations where the custAUDT.cpy is referenced in the project.

CopybooksManagement22

Synchronization from a COBOL - Copybook annotation

You can propagate the annotations contained in a COBOL - Copybook annotation into your copybook file and then through all COBOL files in your project by right-clicking on your COBOL - Copybook annotation file and selecting the Synchronize Annotations entry.

CopybooksManagement23

This can be very useful to propagate annotations which have been automatically created by the modernization process such as Modernized As annotations from ben modernization or transmodeling, since this process is not available on copybook files.

Let's take an example with the custAUDT.cblmf file :

  • The CUSTLOG-AUDIT-INFO record has been previously modernized by the Bean Modernization wizard (see here) and a Modernized As annotation has been automatically created next to the record;

    CopybooksManagement24

  • In order to avoid multiple modernizations of the same record and add information, you may want to propagate this annotation to the copybook and to the other locations of usage. Left-click on your COBOL - Copybook annotation and select the Synchronize Annotations entry as shown above. The annotation synchronization is launched. Once the process has been completed, the following wizard appears to provide the results of the operation :

    CopybooksManagement25

  • You can see that the Modernized As annotation has been reported in the custAUDT.cpy source copybook file, which can be checked by double-clicking on the corresponding annotation in the wizard. It has also be reported in all other locations in the COBOL project.

    CopybooksManagement26

Synchronization from a COBOL file

Annotations synchronization can be directly accessed from a COBOL file, which is a way to synchronize all annotations contained in COBOL - Copybook annotations of this file to their associated copybook files and through them to all other locations in the COBOL project. You can access this propagation mechanism by right-clicking on your COBOL file and selecting the Synchronize Annotations entry in the COBOL Tools menu.

CopybooksManagement27

The process is exactly the same as described before.