Semmle 1.22
Skip to end of metadata
Go to start of metadata

Purpose

By default, the bootstrap tool creates a project configuration with a single build command that extracts all COBOL code found anywhere in the project's source tree – see Tutorial: Basic project creation (COBOL). However, particularly when it comes to including copybooks in the analysis, it may be necessary to customize the project file by specifying additional options.

Usage

The COBOL extractor is written in Java. A typical invocation of the COBOL extractor, as generated by bootstrap for the project file looks like this:

java -jar ${odasa_tools}/extractor-cobol.jar .

This assumes that the variable ${odasa_tools} is set up to point to the tools directory of a Semmle installation, which is always the case during an execution of buildSnapshot.

The extractor takes a single argument ., that is, the current directory. In general, the extractor can be given any number of files and directories as arguments. It traverses the given directories and collects all COBOL files (by default, files with the extension .cbl or .cob). Then it extracts the COBOL code contained in all these files for inclusion in the database.

A project file can contain any number of invocations of the COBOL extractor.

Flags

Flags allow the default behavior of the COBOL extractor to be modified. You can edit an extraction build command in the project file, adding flags to produce the required behavior.

Example build commands 

A simple build command for COBOL extraction such as this:

<build>java -jar ${odasa_tools}/extractor-cobol.jar .</build>

could be modified as follows:

<build>java -jar ${odasa_tools}/extractor-cobol.jar --quiet --tolerate-parse-errors .</build>

In the above example, flags have been added to tell the extractor to report success (return '0') even in the presence of parse errors, and without outputting diagnostic information.

<build>java -jar -Dkoopa.sources=cbl -Dkoopa.copybooks=cob ${odasa_tools}/extractor-cobol.jar --free --copybooks copybooks src lib</build>

In the above example, an extensive reconfiguration has been used to tell the extractor to:

  • Treat .cbl files as COBOL source files.
  • Treat .cob files as COBOL copybooks.
  • Treat all source files as being written using free format .
  • Enable copybook processing and look for copybooks in the copybooks directory as well as alongside the file containing the COPY statement.
  • Only process files in the src and lib top-level directories.

Flag details

The COBOL extractor supports the following flags:

FlagsValueExampleNotes
--freenone Set reference format to FREE. Note that compiler directives in the source files are also respected, so this is not usually required.
--fixednone Set reference format to FIXED (default).
--variablenone
Set reference format to VARIABLE.
--quietnone 

Do not produce diagnostic output.

--tolerate-parse-errors none 

By default, if a parse error is found the extractor exits. If parse errors are acceptable then you can tell the extractor to ignore the error and continue by specifying this flag.

This flag usually works well. Source files that cannot be parsed successfully are extracted with information about the error. Any parse errors found during extraction are reported by the query: Parse error.

--copybooksa directory namesrc/copy

Enable copybook processing. When encountering a COPY statement in a given file, look for copybooks in the given directory after the directory containing the current file. May be specified multiple times, and the directories will be searched in the order given.

Java properties

The COBOL extractor also respects two Java properties:

FlagsValueDefaultNotes
koopa.cobol.sourceslist of extensionscbl,cobFiles with these extensions are treated as COBOL source files.
koopa.cobol.copybookslist of extensionscpy,copyFiles with these extensions are treated as COBOL copybooks.