Windows Stack Installation Guide


Version 4.2.459.0

1. Introduction

Starting from version 4.2.*.* Raincode Legacy Compilers and Tools for Windows support two environments:

  • .NET Framework 4.8

  • .NET 6.0

If you are upgrading your Raincode Legacy Compilers and Tools from an older version, or you are switching from .NET Framework 4.8 to .NET 6.0 environment, it is highly advisable to follow our Version upgrade guide to prevent any potential compatibility issues.
Raincode Legacy Compilers and Tools also install Raincode QIX , Raincode IMSql and Raincode zTrieve.

1.1. Available installers

The tools are deployed with dedicated installers for each of the supported environments.

Even though both installations can coexist on a single system, it is advised that this scenario is used only in upgrading from .NET Framework 4.8 to .NET 6.0 environment.

2. Raincode Net48 installer

Installs Raincode Legacy Compilers and Tools targeting .NET Framework 4.8 environment

The default installation directory is: C:\Program Files\Raincode\Compilers\net48

Created environment variables during the installation process (both pointing to the installation directory):

  • RCDIR

  • RCDIR_NET48

2.1. Prerequisites

Raincode Legacy Compilers and Tools for the .NET Framework 4.8 environment require:

  • A previously installed .NET Framework 4.8 SDK. (Get it here)

  • Windows SDK 10

    • Windows SDK can be available in two ways:

      • Download it here

      • Select Windows 10 SDK from the Individual components while installing the Microsoft Visual Studio 2019

2.2. Dependencies

Raincode Legacy Compilers for .NET Framework depend upon two tools:

  • The .NET assembler ilasm

  • Optionally, the .NET verifier peverify

If you intend to utilise the Raincode Legacy Compilers flexibility and openness by plugging in your own .NET components, such as a homegrown CICS (Customer Information Control System) facility. In that case, you will need a .NET development environment, such as Microsoft Visual Studio 2019.

2.3. Installation

2.3.1. Install

To Install the Raincode Legacy Compilers and Tools, execute the following steps:

  • Double-click the Raincode Legacy Compilers and Tools installer package for the .NET Framework 4.8 environment (one of the Available installers), and the Welcome screen will appear.

welcomescreen
Figure 1. Raincode Legacy Compiler’s Welcome screen
  • Click the Next button, and the End-User License Agreement screen will appear.

enduserlicense
Figure 2. Raincode Legacy Compilers Licensing Agreement
  • Select I accept the terms in the License Agreement, click the Next button, and the Product Features screen will appear.

productfeature 1
Figure 3. Raincode Legacy Compilers Default Product Features screen
  • Select product(s) in the Product Features screen.

productfeature 2
Figure 4. Raincode Legacy Compilers Selected Product
  • After selecting, click the Install button to continue with the Raincode Legacy Compilers and Tools installation. The installation progress indicator screen will appear

installationprogressindicator
Figure 5. Raincode Legacy Compilers - Installation progress indicator screen
  • Click the Finish button to complete the installation.

finish
Figure 6. Raincode Compilers - Installation complete screen
A dialog might appear during the installation process, warning that PEVerify could not be located. This is just a warning; the installation will proceed normally.
A dialog might appear during the installation process, warning that rc.exe could not be located. This is just a warning; the installation will proceed normally.

Once the Raincode Legacy Compilers and Tools installation has been completed, you can use Raincode Legacy Compilers through the Command Prompt window. For more information about:

If you wish to integrate Raincode Legacy Compilers and Tools with your Microsoft Visual Studio (See Raincode Legacy Compilers Visual Studio Integration), please follow Raincode Language Service installer instructions.

2.3.2. Change, repair or remove

The Change, repair or remove installation screen will appear when installing the same installation package more than once.

change48
Figure 7. Raincode Legacy Compilers - Change repair remove screen
  • Click the Change button to change the previously installed version of the Raincode Legacy Compilers and Tools.

change48 1
Figure 8. Raincode Legacy Compilers - change the previously installed version
  • Click the Repair button to repair the previously installed version of the Raincode Legacy Compilers and Tools.

Repair48
Figure 9. Raincode Legacy Compilers - repair the previously installed version
  • Click the Remove button to remove the previously installed version of the Raincode Legacy Compilers and Tools.

Remove48
Figure 10. Raincode Legacy Compilers - remove the previously installed version

A pop-up window with a warning message will appear when installing a different version.

image014
Figure 11. Raincode Legacy Compilers Warning Pop Up

The existing version needs to be removed to install a different version.

3. Raincode Net60 installer

Installs Raincode Legacy Compilers and Tools targeting .NET 6.0 environment

The default installation directory is C:\Program Files\Raincode\Compilers\net6.0.

Created environment variables during the installation process (both pointing to the installation directory):

  • RCDIR

  • RCDIR_NET60

3.1. Prerequisites

Raincode Legacy Compilers and Tools for the .NET 6.0 environment require:

  • A previously installed .NET 6.0 SDK. (Get it here)

  • Windows SDK 10

    • Windows SDK can be available in two ways:

      • Download it here

      • Select Windows 10 SDK from the Individual components while installing the Microsoft Visual Studio 2022

3.2. Dependencies

Raincode Legacy Compilers for .NET 6.0 depends upon two tools:

  • The .NET 6.0 assembler ilasm - deployed as part of the installation in the bin folder

  • Optionally, the .NET 6.0 verifier ILVerify - more information can be found here

If you intend to take advantage of the Raincode Legacy Compilers flexibility and openness by plugging in your own .NET components, for example, for a homegrown CICS (Customer Information Control System) facility, you will need a .NET development environment as well, such as Microsoft Visual Studio 2022.

3.3. Installation

3.3.1. Install

To Install the Raincode Legacy Compilers and Tools, execute the following steps:

image001
Figure 12. Raincode Legacy Compiler’s Welcome screen
  • Click the Next button, and the End-User License Agreement screen will appear.

image002
Figure 13. Raincode Legacy Compilers Licensing Agreement
  • Select I accept the terms in the License Agreement, click the Next button, and the Product Features screen will appear.

image003 1
Figure 14. Raincode Legacy Compilers Default Product Features screen
  • Select product(s) in the Product Features screen.

image003 3
Figure 15. Raincode Legacy Compilers Selected Product
  • After selecting, click the Install button to continue with the Raincode Legacy Compilers and Tools installation. The installation progress indicator screen will appear

image006
Figure 16. Raincode Legacy Compilers - Installation progress indicator screen
  • Click the Finish button to complete the installation.

image011
Figure 17. Raincode Compilers - Installation complete screen

Once the Raincode Legacy Compilers and Tools installation has been completed, you can use Raincode Legacy Compilers through the Command Prompt window. For more information about:

If you wish to integrate Raincode Legacy Compilers and Tools with your Microsoft Visual Studio (See Raincode Legacy Compilers Visual Studio Integration), please follow Raincode Language Service installer instructions.

3.3.2. Change, repair or remove

The Change, repair or remove installation screen will appear when installing the same installation package more than once.

image012
Figure 18. Raincode Legacy Compilers - Change repair remove screen
  • Click the Change button to change the previously installed version of the Raincode Legacy Compilers and Tools.

image012 change
Figure 19. Raincode Legacy Compilers - change the previously installed version
  • Click the Repair button to repair the previously installed version of the Raincode Legacy Compilers and Tools.

image012 repair
Figure 20. Raincode Legacy Compilers - repair the previously installed version
  • Click the Remove button to remove the previously installed version of the Raincode Legacy Compilers and Tools.

image013
Figure 21. Raincode Legacy Compilers - remove the previously installed version

A pop-up window with a warning message will appear when installing a different version.

image014 1
Figure 22. Raincode Legacy Compilers Warning Pop Up

The existing version needs to be removed to install a different version.

4. Installation directory

The Raincode Legacy Compilers installation directory contents are shown below in Table 1.

Table 1. Installation directory contents
Installation directory contents Description

bin

The runtime: runner and dll.
The binary executables for Raincode Legacy Compilers, QIX, IMSql and additional tools.

documentation

Contains documentations.

includes

Often used CICS and SQL copybooks for COBOL.

plugins

Directory where to put the QIX processing and terminal server plugins

RaincodeLanguageService

Raincode Language Service MSBuild extensions (build tasks, project targets and properties)

rcpackages

Raincode NuGet packages.

samples

Some sample legacy programs.

scripts

Contains raincode code scripts (.rcs).

sql

Rewriting rules and stored procedures.

VisualStudioIntegration

Raincode Language Service VSIX packages for integration with Microsoft Visual Studio.

launcher.bat

Batch file for opening Command Prompt with Raincode Legacy Compilers Environment set.

setenv_rccomp.bat

Batch file for setting up Raincode Legacy Compilers Environment.

rc_config.xml

The rc_config.xml(See Appendix) gives the location of ilasm and peverify and .bat scripts (launcher.bat and setenv_rccomp.bat), setting the compilers in the execution path.

5. Raincode Language Service installer

Raincode Language Service enables users to experience full application development in supported legacy languages.

In this context, it refers to extensions made for: Microsoft Visual Studio integrated development environment, MSBuild build system and dotnet command-line interface.

These extensions are an optional part of the installation process. They are designed to allow you to benefit from Raincode project .rcproj files and special items to improve the user experience when developing legacy applications on .NET.

Depending on the chosen installer from Available installers, the extensions refer to:

All files and paths listed above are relative to the installation directory and are available once the chosen Raincode Legacy Compilers and Tools installation is completed.

5.1. Visual Studio integration

Raincode Language Service Visual Studio extension integrates the support for legacy languages in Visual Studio IDE (See Section Raincode Legacy Compilers Visual Studio Integration).

Make sure that you select specific components during the installation of Microsoft Visual Studio to enable the smooth functioning of the Raincode Language Service Visual Studio extension.

Components:

  • From the Workload tab in Visual Studio Installer, choose .Net desktop development

netdesktopdevelopment
Figure 23. Workload tab
  • From the Individual tab in Visual Studio Installer, choose Windows 11 SDK(10.0.22621.0)

indiviudaltab
Figure 24. Individual tab

The following sections describe how the extension should be installed.

5.1.1. Prerequisites

Raincode Language Service Visual Studio extension requires previously installed Microsoft Visual Studio IDE:

5.1.2. Installation

After completing Raincode Legacy Compilers and Tools installation, a folder VisualStudioIntegration is created at the default install location. This folder contains VS2019 and/or VS2022 subdirectories (depending on the chosen installer and Visual Studio version) with RainCodeLanguageService.vsix file.

Install

To install the Raincode Language Service Visual Studio extension, execute the following steps:

  • Double click the RainCodeLanguageService.vsix to begin the installation.

vs1
Figure 25. VSIX installer
  • Select the product(s) to install the extension and click the install.

vs2
Figure 26. Select product(s)
vs3
Figure 27. Installation in progress
vs4
Figure 28. Installation completed
To install the Raincode Language Service Visual Studio extension, you must ensure that all Microsoft Visual Studio instances are closed before starting the installation process.
Uninstall

You can uninstall the Raincode Language Service Visual Studio extension by executing the following steps:

  • Open Visual Studio and select Extensions→Manage Extensions; under the installed tab, select Language Service for Raincode and press Uninstall.

uninstallraincode
Figure 29. Manage Extensions
  • A pop-up will appear asking about your choice. Press yes to uninstall the Language Service for Raincode.

uninstallraincode1
Figure 30. Uninstalling-Raincode-Language-Service-Visual-Studio-extension
  • Once you select yes, Microsoft Visual Studio will schedule the changes and start the uninstall process when the Visual Studio is closed.

changescheduled
Figure 31. Close Visual Studio to uninstall the Language service for Raincode
  • Click on modify to uninstall the Language service for Raincode

uninstallvs
Figure 32. VSIX Installer
uninstallationinprogress
Figure 33. Uninstallation in progress
uiinstallinprogress
Figure 34. Uninstallation completed

5.2. dotnet CLI integration

Only available with Raincode Net60 installer

Besides integrating the support for legacy languages in Visual Studio IDE, Raincode Language Service also integrates Raincode project .rcproj files and project items with dotnet new CLI.

Additionally, Raincode Language Service supports the manual upgrade of out-of-date Raincode project files with the RaincodeProjectUpgradeTool. RaincodeProjectUpgradeTool is deployed as a dotnet tool, available in rcpackages in the installation directory. It upgrades .rcproj files to be compatible with the current version of the Raincode Language Service extension. Files that do not meet upgrade conditions are left unchanged.

The following sections describe how the features mentioned above should be installed.

5.2.1. Prerequisites

To enable dotnet new integration following actions are required:

  1. Install Microsoft Visual Studio 2022 or higher

  2. Install Raincode Net60 installer

  3. Add Raincode NuGet packages directory to NuGet sources (See NuGet sources configuration)

5.2.2. Installation

Below mentioned steps assume that Visual Studio 2022 was previously installed. This is not mandatory. However, it is required to have dotnet available on PATH.
Item templates install

To install Raincode Language Service item templates, perform the following steps:

  • Open a command prompt and execute the following command:

    dotnet new install RaincodeLanguageService.Item.Templates --nuget-source="path to the directory with .nupkg"
install item templates
Figure 35. Installing item templates
Item templates uninstall

To uninstall Raincode Language Service item templates, perform the following steps:

  • Open a command prompt and execute the following command:

    dotnet new uninstall RaincodeLanguageService.Item.Templates
uninstall item templates
Figure 36. Uninstalling item templates
Project templates install

To install Raincode Language Service project templates, perform the following steps:

  • Open a command prompt and execute the following command:

    dotnet new install RaincodeLanguageService.Project.Templates  --nuget-source="path to the directory with .nupkg"
install project templates
Figure 37. Installing project templates
Project templates uninstall

To uninstall Raincode Language Service project templates, perform the following steps:

  • Open a command prompt and execute the following command:

    dotnet new uninstall RaincodeLanguageService.Project.Templates
uninstall project templates
Figure 38. Uninstalling project templates
RaincodeProjectUpgradeTool install

To install the RaincodeProjectUpgradeTool:

  • Open a command prompt and execute:

     dotnet tool install -g RaincodeProjectUpgradeTool

The output should be the following:

You can invoke the tool using the following command: raincode_project_upgrade_tool
Tool 'raincodeprojectupgradetool' (version '1.0.0') was successfully installed.
RaincodeProjectUpgradeTool uninstall

To remove the RaincodeProjectUpgradeTool:

  • Open a command prompt and execute:

dotnet tool uninstall -g RaincodeProjectUpgradeTool

The output should be the following:

 Tool 'raincodeprojectupgradetool' (version '1.0.0') was successfully uninstalled.

6. Version upgrade guide

Upgrading existing Raincode Legacy Compilers and Tools installation depends on the version that is currently installed on the system.

Therefore, follow the steps from these sections that apply to your scenario.

6.1. Common upgrade steps

  1. Remove the old Raincode Legacy Compilers and Tools installation

  2. Remove the old Raincode Language Service installation

  3. Install the new Raincode Legacy Compilers and Tools version, choose one of the Available installers

  4. Install the new Raincode Language Service version; see: Install Raincode Language Service

Apart from the above-listed common steps, a few additional ones are described in detail in the following sections.

6.2. Relocate license file step

Raincode Legacy Compilers and Tools license file (*.rclic) needs to be relocated if the upgrade is performed:

  • From v4.1.* (or older) to v4.2.*

    • Copy the license file: From the old installation directory (usually: C:\Program Files\Raincode\Compilers) to the new installation directory (usually: C:\Program Files\Raincode\Compilers\net48 or C:\Program Files\Raincode\Compilers\net6.0)

  • From Net48 v4.2.* to Net60 v4.2.*

    • Copy the license file: From the old installation directory (usually: C:\Program Files\Raincode\Compilers\net48) to the new installation directory (usually: C:\Program Files\Raincode\Compilers\net6.0)

6.3. Upgrade project files step

Upgrading the Raincode Legacy Compilers and Tools version can cause outdated project files to stop working properly. For this reason, an upgrade is required for the following:

  • C# projects referencing Raincode libraries (NuGet packages)

  • Raincode project files .rcproj files

6.3.1. Upgrade package dependencies in C# projects

If upgrading from v4.1.* (or older) to v4.2.* Raincode Legacy Compilers and Tools C# projects .csproj, depending on Raincode libraries, such as runners and custom modules, need to be updated to use version 4.2 of the libraries.

Example before:

<ItemGroup>
    <PackageReference Include="RainCodeLegacyRuntime" Version="4.1.*" />
    <PackageReference Include="RainCodeQixInterface" Version="4.1.*" />
    <PackageReference Include="rccorlib" Version="1.0.*" />
</ItemGroup>

Example after:

<ItemGroup>
    <PackageReference Include="RainCodeLegacyRuntime" Version="4.2.*" />
    <PackageReference Include="RainCodeQixInterface" Version="4.2.*" />
    <PackageReference Include="rccorlib" Version="1.0.*" />
</ItemGroup>

6.3.2. Upgrade Raincode project files

Raincode projects .rcproj can be upgraded:

When upgrading the version of Raincode Legacy Compilers and Tools, it is highly advisable to upgrade all of your Raincode projects. Failing to do so, further upgrades might not work as expected since the project upgrades are incremental.

7. Debugging with VSCode plugin

For Windows systems, Raincode Legacy Compilers includes Raincode COBOL Debugger - VSCode extension for debugging programs compiled with Raincode COBOL compiler.

7.1. VSCode plugin prerequisites

Raincode COBOL Debugger requires a previously installed VSCode editor on the target system.

VSCode editor can be installed on Windows systems by following the official documentation.

7.1.1. VSCode plugin installation

  • Open VSCode

  • From the left-hand side palette, select Extensions (or press the Ctrl+Shift+X shortcut)

vscodeextensions
Figure 39. Open VSCode extensions
  • Click the three dots from the Extensions menu on top and select Install from VSIX…​

installfromvsix
Figure 40. Install the extension from VSIX
  • Browse to the folder C:\Program Files\Raincode\Compilers\net6.0\VSCodeIntegration and select cobol-9.3.2.vsix

  • Wait for the installation to finish.

  • Browse to the C:\Program Files\Raincode\Compilers\net6.0\VSCodeIntegration and select raincode-cobol-debugger-1.0.0.vsix

  • Wait for the installation to finish.

  • In the extensions list, find Raincode COBOL Debugger and click on it. Details about the extension will appear on the right-hand side.

raincodedebugger
Figure 41. Raincode COBOL Debugger Details
  • Follow through the guide in the Details description of the extension to activate it, prepare your COBOL environment and start debugging.

  • Execute the script C:\Program Files\Raincode\Compilers\net6.0\VSCodeIntegration\windows\CreateLinkFile.sh to create a link file that enables the debbuger to display the value of the variables.

  • Once you go through all the steps, your debug session should look similar to the screenshot below.

debuggersession
Figure 42. Raincode COBOL Debugger Debug Session

Appendix A: NuGet sources configuration

In order to build a project that references a NuGet package, the package first needs to be obtained from a known source. Depending on the way the project is built, the sources can be configured through:

All Raincode NuGet packages are deployed in the rcpackages folder in the installation directory. This path needs to be added as the user-defined NuGet source before building projects referencing them.

A.1. Add user-defined NuGet source

Add the Raincode NuGet packages directory to the NuGet sources.

This example assumes that Visual Studio 2022 was previously installed. This is not mandatory. However, it is required to have dotnet available on PATH.
  1. Open a command prompt and execute:

    dotnet nuget add source -n RaincodePackages-Net6.0-4.2.459.0 "%RCDIR%\rcpackages"
  2. Verify that the operation was completed successfully by executing:

     dotnet nuget list source

The result of the previous steps should look like this.

nuget add source
Figure 43. Adding Raincode NuGet packages as NuGet source

A.2. Remove user-defined NuGet source

Remove the Raincode NuGet packages directory from the NuGet sources.

This example assumes that Visual Studio 2022 was previously installed. This is not mandatory. However, it is required to have dotnet available on PATH.
  1. Open a command prompt and execute:

    dotnet nuget remove source RaincodePackages-Net6.0-4.2.459.0
  2. Verify that the operation was completed successfully by executing:

     dotnet nuget list source

The result of the previous steps should look like this.

nuget remove source
Figure 44. Removing Raincode NuGet packages as NuGet source