Enabling CGI support

You need to enable CGI support to generate applications that use Embedded HTML.

To use Embedded HTML, you must have the following in place:

Project Specifications

  • Your Visual Studio project must be a Native COBOL project using the Console Application output type or template.
  • In the project properties, set the Run-time Model on the COBOL Link Settings tab to Dynamic.

Server Specifications

Apache server:

You need to configure the server as shown below. This example was created with Apache 2.4.

  • Enable mod_cgi
    LoadModule cgi_module modules/mod_cgi.so
  • Enable mod_env
    LoadModule env_module modules/mod_env.so
  • Specify a /cgi-bin script alias. For example:
    <IfModule alias_module>
     ScriptAlias /cgi-bin/ "${SRVROOT}/cgi-bin/"
    </IfModule>
  • Enable ExecCGI for the directory that contains your cgi executable. For example:
    <Directory "${SRVROOT}/cgi-bin">
        AllowOverride None
        Options None
        Require all granted
    </Directory>
  • Micro Focus Licensing Specifications
    If you are using a version of the COBOL Run-Time System earlier than the one supplied with the latest Visual COBOL, you must set the MFCES_INIT_LOCATION environment variable to point to your ces.ini file. For example:
    SetEnv MFCES_INIT_LOCATION "c:\programdata\micro focus\ces.ini"

IIS server:

The following instructions use Information Services Manager (IIS) 10.0 and Windows 10.

You can deploy in the default location for IIS, C:\inetpub\wwwroot\cgi-bin. Alternatively, you can configure your project to create a site directory structure, and then configure your IIS server to use that location. See Deploying a CGI Application with Embedded HTML and the CGI samples available with Samples Browser.

Unrestricted CGI application present a security risk to your system. Because of this, you need to configure IIS to enable CGI programs to execute. IIS runs under a special user name IUSR and you need to grant this user permissions to the site directory structure.

IIS must be enabled in your Windows system - see the Microsoft documentation for instructions. You need to manually enable CGI support as follows:

  1. Open the Control Panel and select Programs.
  2. Click Turn Windows features on or off.
  3. Enable World Wide Web Services > Application Development Features > CGI.

To configure IIS to use a non-default installation location for the executables:

  1. Start IIS.
  2. In the Connections pane, expand the machine name node.
  3. Right-click Sites and click Add Website.
  4. Specify a Site name.
  5. In the Physical path box, type the full path to the site directory created by your Visual Studio solution such as pathtosolution\site.
  6. It is recommended to change the Port (for example, to 81) to avoid clashes with the default site. If the default site is not running, it is safe to use port number 80.
  7. Click OK.

You also need to configure some IIS security features to enable CGI programs to execute in the site directory structure:

  1. In IIS, in Connections, click on the top level machine name node and double-click ISAPI and CGI Restrictions.
  2. Click Add in the Actions pane.
  3. Specify the full path name and the file name of your project's executable in the ISAPI or CGI path text box - for example, pathtosolution\site\cgi-bin\app.exe.
  4. Check Allow extension path to execute, and click OK.
  5. Expand Sites, right-click the Web site you have just added, and click Edit Permissions.
  6. Select the Security tab.
  7. Click Edit, then click Add.
  8. Click Locations, select the machine name, and click OK.
  9. Enter IUSR into the text box and click OK.

    IUSR now appears in the Security pane with the following permissions enabled - Read and & execute, List folder contents, and Read.

  10. Click OK until these dialogs are closed.
  11. Restart the machine node in order to apply all of these changes - click Restart in the Actions pane.

    You should now be able to debug your CGI application from the Visual Studio solution.

You also need to enable the IIS web.config file in your site to work. The file controls the actions allowed by the web server on the directory.

  1. Start a command prompt with Administrator's privileges.
  2. Execute the following command:
    %windir%\system32\inetsrv\appcmd.exe unlock config /section:system.webServer/handlers

    You should receive the following message: Unlocked section "system.webServer/handlers" at configuration path "MACHINE/WEBROOT/APPHOST".