Introduction: Configuring Visual Studio Projects

Previously I showed how to create a project for Visual Studio (VS) for use with Micro Focus Visual COBOL/Enterprise Developer. Now that the project has been created and COBOL sources added, let's explore what's needed to set up the directives needed to be able to build the project. Directives are options that are passed to the compiler. They configure how the COBOL source code should be transformed to machine code, that is suitable for running on the target platform.

Working with directives

When building COBOL applications without the use of a project system, directives are typically passed directly to the compiler or through the use of a .dir file. For developers unfamiliar with a .dir file, it is simply a file that contains a list of compiler directives.

With the VS project system, project properties are stored in the project (.cblproj) file. Most project properties map to a compiler directive. These properties get transformed by the MSBuild tool and are passed to the COBOL compiler, irrespective of whether the build is occurring through the IDE or the command line.

Directives precedence

To understand how to work with directives in the Integrated Development Environment (IDE), it is important to have an understanding of how directives eventually get passed to the compiler. Shown below is the ordering of directives that are used by the COBOL compiler when building through MSBuild. Micro Focus strongly recommends using Properties to specify directives except in the case where no corresponding property exists; then Additional Directives can be used. This avoids potentially overriding directives unintentionally.

1. cobol.dir file
   • MSBuild invokes the COBOL compiler with the project directory as the working directory. As a result, this file will be picked up by the compiler if it exists in the project directory.
   • Generally, it is not advised since it is liable to be overridden by default project properties. It is better to define a .dir file with a different name and explicitly set the use directive in the project-level Additional Directives
2. Project properties (Recommended)
3. Project-level Additional Directives
4. File properties
5. File-level Additional Directives
6. Inside source file ($SET statement)

Project properties

Project properties are the preferred way to configure directives. To set a project property, simply double click on the Properties item under the project in the Solution Explorer. From here it is possible to set various properties. The most notable ones under the COBOL tab that should be looked at are:

• Platform
• COBOL Dialect
• Source Format
• Compile For Debugging
• Output Path

Note that in VS, there is a concept of build configurations for project properties. This allows different project properties to be set for different build configurations. By default, the properties shown will be for the current Active Build Configuration. It is possible to select and modify different build configurations using the dropdowns (configuration/platform) shown at the top of the properties page. For example, by default the Debug configuration sets the Compile for debugging property, whilst the Release configuration does not.

File properties

File properties can be accessed by right clicking on the file item in Solution Explorer and selecting Properties. A dialog will be shown that allows the developer to configure any directives that are specific to the that individual file. This can be useful if for example certain source files use different source formats or COBOL dialects.

Note that file properties are not affected by the Active Build Configuration and will always be used. Additionally, file properties are only available for native COBOL projects and managed Mainframe Subsystem (MSS) projects.

Additional Directives

Additional directives can be set in the Project Properties page or the File Properties dialog. These are essentially project/file properties whose contents get appended to the command line arguments, but only after all other properties have been handled.

It is possible to override existing properties here, so use with care. Avoid setting any directives that are already available as a property (e.g. source format, dialect etc).

User defined .dir file

A .dir file can be a convenient way of sharing directives. They contain a list of directives, which can be useful if the same set of directives is needed in multiple projects. To include the file, copy the file into the project folder and in Additional Directives set the use directive.

use(foo.dir)

As the directives are being set as part of Additional Directives, a degree of care is required to avoid overwriting project/file properties.

Migrating directives into a project

To move the directives required to build a COBOL application into a project, the following is a rough outline of the approach I would use.

1. Identify common directives. These could be from an existing .dir file or script of some kind.
   • Extract out directives that are represented by project properties and set them. Our docs lists some of the directives that are mapped.
   • For any directives that are not mapped, put them in the project level Additional Directives. If these directives are not shared by other projects, then add them directly. Otherwise it may be simpler to set the use directive in conjunction with a .dir file.
2. Identify unique directives that are specific to certain files.
   • Set any mapped directives as file properties.
   • For any directives that are not mapped, put them in the file level Additional Directives.

Note that for any directives that are stored directly in project-level Additional Directives (i.e. not in a .dir file), VS has a built in directives scanning functionality. This scanner gets run the first time a project gets loaded (if enabled) and will prompt the user if it detects any mapped directives that are being used in Additional Directives.

Afterword

In this post, I've covered how to configure directives for COBOL projects. For further info on moving to a project system, please see the Micro Focus docs or reach out on the community site.