Interactive COBOL Web Server Revision 4.89 15-Dec-2015 Interactive COBOL (ICOBOL) provides a common development and runtime environment on Windows, Linux, and UNIX that allows complete applications (including code and data) to be moved from one system to another without change. The ICOBOL Web Server runtime (cgiCOBOL) enables the use of COBOL programs as Common Gateway Interface (CGI) scripts, initiated across the Internet by request from a World Wide Web (WWW) browser through a Hyper-Text Transfer Protocol (HTTP) server. cgiCOBOL programs can be written using standard ANSI COBOL syntax. The cgiCOBOL components are supplied in a separate directory of the installation and consist of the following files: cgicobol icruncgi[.exe] - cgiCOBOL Runtime System executable binary scripts - application (program) scripts directory cgidemo.sr - demonstration program source cgidemo.cx - demonstration program compiled executable cgilogon.sr - sample login program source cgilogon.cx - sample login program compiled executable httpd-cgicobol.conf - sample Apache configuration information images - application (graphical) images directory cgidemo.gif - demonstration program graphic image cgilogon.gif - sample login graphic image docs - application (HTML) document directory cgidemo.htm - used by the demonstration program cgiCOBOL development has been primarily focused on the following server platforms: - Apache HTTP Server on Linux and Windows Server - Microsoft Internet Information Server (IIS) on Windows Servers Browsers tested: - Internet Explorer 7... - Firefox According to a Netcraft Web Server Survey (January 2011), Apache and IIS account for 80% of sites (more than 284,000,000) polled. The breakdown is: Apache - 60.10% Microsoft IIS - 20.04 What is CGI? ------------ The following is from http://hoohoo.ncsa.uiuc.edu/cgi/intro.html which is the NCSA (National Center for Supercomputing Applications) site: "The Common Gateway Interface (CGI) is a standard for interfacing external applications with information servers, such as HTTP or Web servers. A plain HTML document that the Web daemon retrieves is static, which means it exists in a constant state: a text file that doesn't change. A CGI program, on the other hand, is executed in real-time, so that it can output dynamic information. For example, let's say that you wanted to "hook up" your Unix database to the World Wide Web, to allow people from all over the world to query it. Basically, you need to create a CGI program that the Web daemon will execute to transmit information to the database engine, and receive the results back again and display them to the client. This is an example of a gateway, and this is where CGI, currently version 1.1, got its origins." The NCSA site has much good information about writing CGI programs. The address is: http://hoohoo.ncsa.uiuc.edu/cgi What is cgiCOBOL (icruncgi) ---------------------------- ICRUNCGI is a special version of the ICOBOL runtime tailored to be run under control of a Web server. It always assumes an ICTERM=file, quiet operation, and no logon mode. The ICRUNCGI environment variable can be set to provide a common set of switches. It will use consoles that have the device name of "cgi". It uses ICRUNCGI licenses from ICPERMIT. ICRUNCGI cannot be run in debug mode. ICRUNCGI expects to see two initial environment variables, GATEWAY_INTERFACE and PATH_TRANSLATED. GATEWAY_INTERFACE gives the current version of the gateway usually CGI/1.1 and is used by ICRUNCGI to determine it is running under control of a Web server. PATH_TRANSLATED provides the command-line to be run. The REQUEST_METHOD environment variable is passed to the CGI program to instruct it as to the type of CGI request being made. When the CGI program is requested with the GET method, any data is passed through the QUERY_STRING environment variable. To get the data, use the IC_GET_ENV builtin to read the environment variable. When the CGI program is requested with the POST method, any data is passed through standard input and the environment variable CONTENT_LENGTH will hold its length. To get the data, perform a READ for CONTENT_LENGTH bytes using RECORD DELIMITER IS SIZE in the SELECT and RECORD IS VARYING IN SIZE DEPENDING ON in the FD with ICOBOL 3 or greater. (Under ICOBOL 2 this required 1-byte reads.) Updates -------- 4.80 - 4.89 ----------- None. 4.70 - 4.72 ----------- None. 4.60 ---- None. 4.51 - 4.55 ----------- None. 4.50 ---- 1. The cgidemo.sr program has been updated with some new server veriables, multi-byte reads of STDIN, Cookie usage, and some clean up. 2. This readme has been updated with testing using Apache 2.2 3. The cgilogon.sr program has had minor updates and cleanup. 4. icruncgi has been updated to handle spaces in the argument to PATH_TRANSLATED. IE the URL. cgiCOBOL on Apache for RedHat Linux ----------------------------------- This discussion assumes that Apache has been installed using the default directory of {/home/apache}. In a 2.2.17 install, this structure looks like: webspace: /home/apache/htdocs - the DocumentRoot directory /home/apache/cgi-bin - cgi scripts /home/apache/icons - location of icons used with Apache administrative: /home/apache/bin - executables /home/apache/build - build tree /home/apache/conf - configuration files /home/apache/error - default errors /home/apache/include - include files for build /home/apache/lib - libraries /home/apache/logs - log files /home/apache/man - man pages /home/apache/manual - html documentation /home/apache/modules - contains various shared object files The setup described below has been used in testing and should work if implemented as described. Setup ----- 1. Create a cgicobol directory alongside the DocumentRoot directory; copy the contents of the cgicobol release directory there. For example, if the DocumentRoot directory is {/home/apache}/htdocs: su mkdir {/home/apache}/cgicobol cd /udd/icobol_release/cgicobol find . -print | cpio -pdmv {/home/apache}/cgicobol You will need to minimially have the following setup: {/home/apache}/cgicobol/icruncgi {/home/apache}/cgicobol/scripts/cgidemo.cx {/home/apache}/cgicobol/scripts/cgilogon.cx {/home/apache}/cgicobol/images/cgidemo.gif {/home/apache}/cgicobol/images/cgilogon.gif {/home/apache}/cgicobol/docs/cgidemo.htm The icrun and icsys shared libraries should be installed in the standard user library location. 2. Modify the default Apache configuration files as shown below to get the cgiCOBOL mechanism working. The ScriptLog directive should be commented out once things are working because it is detrimental to performance. Be aware that other modifications may need to be made to these files, depending on your needs and preferences. For example, you may not want to permit server-side includes from certain directories. We recommend you first make the changes necessary to get cgiCOBOL working. Then make any other needed changes. Add the following directives to the Apache configuration file (httpd.conf). (Older versions of Apache used three configuration files - httpd.conf, access.conf, and srm.conf.) Add the following to file httpd.conf: # icruncgi is in here AllowOverride None Options ExecCGI FollowSymLinks Allow from all # Add aliases for the images and docs directories Alias /cgicobol/images/ {/home/apache}/cgicobol/images/ Alias /cgicobol/docs/ {/home/apache}/cgicobol/docs/ # Designate the cgicobol directory as containing scripts ScriptAlias /cgicobol/ {/home/apache}/cgicobol/ # Specify a handler for .cx files AddHandler icobol-handler cx # Specify an action for the icobol handler; the action is to # execute icruncgi and pass the .cx file to it Action icobol-handler /cgicobol/icruncgi # Set any specific environment variables needed # Make sure ICROOT is available when icruncgi is executed by # setting it here ##SetEnv ICROOT /udd/icobol_release # If you need to set LD_LIBRARY_PATH then set it here ##SetEnv LD_LIBRARY_PATH /udd/icobol_release # Switches may be passed to icruncgi through the ICRUNCGI # environment variable. For example, this will cause an # icruncgi.lg file in /tmp to be appended each time icruncgi # is invoked. ##SetEnv ICRUNCGI "-q -A /tmp:a" These can be done in one step by including the provided httpd-cgicobol.con file. That can be done by moving it to the conf/extra directory and then adding the following Include: Include conf/extra/httpd-cgicobol.conf Check the following in httpd.conf: # Add logging of scripts for debugging - comment out once things # are working ScriptLog logs/script_log # Change LogLevel from warn to debug until things are working # correctly # LogLevel warn LogLevel debug If Apache is secure (SSL-enabled), add the following to httpd.conf in the _default_:443 Virtual Host section: # Enable SSL cgi environment variables for cgiCOBOL scripts SSLOptions +StdEnvVars +CompatEnvVars After making changes to the configuration files, restart apache. On Redhat 6.0 where Apache is installed by RPM, this is done by: /etc/rc.d/init.d/httpd restart For non-Redhat installations, restart Apache using the apachectl script: /usr/local/apache/bin/apachectl start 3. Run icconfig, and define several logical consoles (@CONs) to run on device "cgi". Make sure they are enabled. Make sure they are set to run programs. You should define enough of these cgi consoles to support the number of simultaneous hits to ICOBOL CGI scripts you expect on your site. If you do not have cgi consoles defined and someone attempts to connect, the server will return an error since icruncgi will fail with a "no more unassigned consoles" error. Different browsers may display different errors in this situation. For example, Internet Explorer 5 reports that "The page cannot be displayed - cannot find server or DNS error". Netscape Navigator Gold 3.01 returns a "Document contains no data" error. Switches may be passed to icruncgi through the ICRUNCGI environment variable. This can be set from icconfig or in the Apache configuration file as shown above. 4. Restart icexec. 5. To access the cgidemo program, point your browser to: http:///cgicobol/scripts/cgidemo.cx 6. Apache will allow you to specify program switches after the cgidemo.cx portion. For example: http:///cgicobol/scripts/cgidemo.cx/A cgiCOBOL on Apache for Wndows ----------------------------------- Notes: A) Not installing under "Program Files" allows for easier configuration as files are not as protected. B) In Windows the forward slash is still used as a directory separator in configurations. This discussion assumes that Apache has been installed using the default directory of {C:/users/apache}. In a 2.2.17 install, this structure looks like: webspace: c:/users/apache/htdocs - the DocumentRoot directory c:/users/apache/cgi-bin - cgi scripts c:/users/apache/icons - location of icons used with Apache administrative: c:/users/apache/bin - executables c:/users/apache/build - build tree c:/users/apache/conf - configuration files c:/users/apache/error - default errors c:/users/apache/include - include files for build c:/users/apache/lib - libraries c:/users/apache/logs - log files c:/users/apache/man - man pages c:/users/apache/manual - html documentation c:/users/apache/modules - contains various shared object files The setup described below has been used in testing and should work if implemented as described. Setup ----- 1. Create a cgicobol directory alongside the DocumentRoot directory; copy the contents of the cgicobol release directory there. For example, if the DocumentRoot directory is {c:/users/apache}/htdocs: su md {c:\users\apache}\cgicobol cd c:\program files\icobol\cgicobol copy /s * {c:/users/apache}/cgicobol You will need to minimially have the following setup: {c:/users/apache}/cgicobol/icruncgi.exe {c:/users/apache}/cgicobol/scripts/cgidemo.cx {c:/users/apache}/cgicobol/scripts/cgilogon.cx {c:/users/apache}/cgicobol/images/cgidemo.gif {c:/users/apache}/cgicobol/images/cgilogon.gif {c:/users/apache}/cgicobol/docs/cgidemo.htm The icrun and icsys .dlls will already be installed correctly. 2. Modify the default Apache configuration files as shown below to get the cgiCOBOL mechanism working. The ScriptLog directive should be commented out once things are working because it is detrimental to performance. Be aware that other modifications may need to be made to these files, depending on your needs and preferences. For example, you may not want to permit server-side includes from certain directories. We recommend you first make the changes necessary to get cgiCOBOL working. Then make any other needed changes. Add the following directives to the Apache configuration file (httpd.conf). (Older versions of Apache used three configuration files - httpd.conf, access.conf, and srm.conf.) Add the following to file httpd.conf: # icruncgi is in here AllowOverride None Options ExecCGI FollowSymLinks Allow from all # Add aliases for the images and docs directories Alias /cgicobol/images/ {c:/users/apache}/cgicobol/images/ Alias /cgicobol/docs/ {c:/users/apache}/cgicobol/docs/ # Designate the cgicobol directory as containing scripts ScriptAlias /cgicobol/ {c:/users/apache}/cgicobol/ # Specify a handler for .cx files AddHandler icobol-handler cx # Specify an action for the icobol handler; the action is to # execute icruncgi and pass the .cx file to it Action icobol-handler /cgicobol/icruncgi.exe # Set any specific environment variables needed # Switches may be passed to icruncgi through the ICRUNCGI # environment variable. For example, this will cause an # icruncgi.lg file in c:/users/tmp to be appended each time # icruncgi is invoked. Make sure c:/users/tmp exists. ##SetEnv ICRUNCGI "-q -A c:/users/tmp:a" These can be done in one step by including the provided httpd-cgicobol.con file. That can be done by moving it to the conf/extra directory and then adding the following Include: Include conf/extra/httpd-cgicobol.conf Check the following in httpd.conf: # Add logging of scripts for debugging - comment out once things # are working ScriptLog logs/script_log # Change LogLevel from warn to debug until things are working # correctly # LogLevel warn LogLevel debug If Apache is secure (SSL-enabled), add the following to httpd.conf in the _default_:443 Virtual Host section: # Enable SSL cgi environment variables for cgiCOBOL scripts SSLOptions +StdEnvVars +CompatEnvVars After making changes to the configuration files, restart apache. 3. Run icconfig, and define several logical consoles (@CONs) to run on device "cgi". Make sure they are enabled. Make sure they are set to run programs. You should define enough of these cgi consoles to support the number of simultaneous hits to ICOBOL CGI scripts you expect on your site. If no cgi consoles are defined and someone attempts to connect, the server will return an error since icruncgi will fail with a "no more unassigned consoles" error. Different browsers may display different errors in this situation. For example, Internet Explorer 5 reports that "The page cannot be displayed - cannot find server or DNS error". Netscape Navigator Gold 3.01 returns a "Document contains no data" error. Switches may be passed to icruncgi through the ICRUNCGI environment variable. This can be set from icconfig or in the Apache configuration file as shown above. 4. Restart icexec. 5. To access the cgidemo program, point your browser to: http:///cgicobol/scripts/cgidemo.cx 6. On Windows program switches cannot be specified after the cgidemo.cx portion. For example: http:///cgicobol/scripts/cgidemo.cx/A will not work under Windows. Apache Information Resources ---------------------------- Web: www.apache.org - apache documentation available here Newsgroup: comp.infosystems.www.servers.unix - an excellent resource; members of the Apache Group frequent this. Books: "Apache: The Definitive Guide" from O'Reilly and Associates, (ISBN: 1-56592-525-9) - written by a member of the core Apache Group "Apache Server Administrator's Handbook" by Mohammed J. Kabir, (ISBN: 0-7645-3306-1) cgiCOBOL on Microsoft Internet Information Server (IIS) ------------------------------------------------------- This discussion assumes that you have alread set up a web site under IIS. This configuration was tested under Microsoft-IIS/4.0. In the discussion below, "to check" an option means to click the associated checkbox to select it (i.e., put a checkmark in it); "to uncheck" means clicking the checkbox to deselect it (remove the checkmark). 1. Create a new folder named cgicobol, preferably parallel to the document root of your website. Copy the cgicobol release folder from the ICOBOL installation to the newly-created cgicobol folder. This will result in three directories in the cgicobol folder (docs, images, scripts). You will need to minimially have the following setup: \Inetpub\cgicobol\icruncgi.exe \Inetpub\cgicobol\scripts\cgidemo.cx \Inetpub\cgicobol\scripts\cgilogon.cx \Inetpub\cgicobol\images\cgidemo.gif \Inetpub\cgicobol\images\cgilogon.gif \Inetpub\cgicobol\docs\cgidemo.htm 2. From the Microsoft Management Console (MMC), create a virtual directory named cgicobol on your website, and make its local path point to the cgicobol folder. Right-click on cgicobol to open its properties sheet. Select the Virtual Directory tab. Under Content Control, uncheck the Index this directory box, and check Log Access. Under Access Permissions, leave both Read and Write unchecked. Set the Application Settings Permissions to None. Click the Configuration button. Select the App Mappings tab on the resulting dialog box, and define the .cx extension. Set the path to the icruncgi.exe executable, which is in the cgiCOBOL folder. 3. From the MMC, right-click in turn on each of the three folders (scripts, images, and docs) contained in the cgicobol virtual directory. For scripts, set the Application Settings Permissions to Script. Under Access Permissions, both Read and Write should be unchecked. Under Content Control, uncheck Index this Directory and check Log Access. For images and docs, set the Application Settings Permissions to None. Under Access Permissions, check Read to set it. Under Content Control, uncheck Index This Directory, and check Log Access. Exit the MMC. 4. Run the configuration editor (either icconfig or icedcfw), and define several consoles to run on device "cgi". Make sure they are enabled. Make sure they are set to run programs. You should define enough of these cgi consoles to support the number of simultaneous hits you expect on your site. If you do not have cgi consoles defined and someone attempts to connect, the server will return an error since icruncgi will fail with a "no more unassigned consoles" error. Switches may be passed to icruncgi through the ICRUNCGI environment variable. This can be set from icconfig. 5. Restart icexec. 6. Point your browser to: http:///cgicobol/scripts/cgidemo.cx 7. IIS will not allow you to pass program switches appended to cgidemo.cx. For example: http:///cgicobol/scripts/cgidemo.cx/A This URL will cause an error 404, "Page not found" error under IIS. If your cgiCOBOL program must be invoked with program switches, you can create a front-end program which uses the CALL PROGRAM statement to invoke the program with the desired switches. IIS Information Resources ------------------------- Book: "Administering IIS4" by Mitch Tulloch (ISBN: 0-07-065536-7) Web: Check www.microsoft.com for information. Newsgroup: microsoft.public.inetserver.iis Troubleshooting --------------- The nature of cgi scripts makes debugging them difficult. However, there are some things you can do to make it easier: * With revisions 3.13 and greater of ICOBOL use the @AUDIT facility to send audit messages to the runtime audit log. * Insert temporary code in the cgi script to output useful information such as location or values. * To run icruncgi standalone you will have to duplicate the CGI environment. Set GATEWAY_INTERFACE to some non blank value Set PATH_TRANSLATED to the commandline to execute: \users\programs\scripts\cgidemo.cx, for example. Set REQUEST_METHOD to GET or POST For a GET set QUERY_STRING if needed For a POST set CONTENT_LENGTH and provide the input thru stdin Set ICRUNCGI to enable auditing, say -ai Make sure you have a console enabled for CGI as cg. Make sure you have an icruncgi license. Finally: icruncgi >output.htm (For a GET) or cat data | icruncgi >output.htm (For a POST) The output.htm file can be viewed in a browser to see the result and icruncgi.lg can be viewed for any runtime errors. Apache ------ Look in the Apache log files for clues to problems. By default they will be in a directory named logs in the directory specified by the ServerRoot directive. Errors are logged in error_log; access information is in access_log. For an SSL-enabled Apache, an additional logfile named ssl_engine_log is kept. If a script log was defined as recommended, then error output from the cgiCOBOL runtime or the ICOBOL CGI program may be found there. Output in script_log shows that the cgiCOBOL runtime tried to execute something. Become the user that will be trying to execute the scripts as Apache. By default this is user nobody. Permission problems may be reported as some other type of problem. Trying to run the scripts by hand as this user may reveal permission problems. IIS --- Check the Event Viewer for error messages. Check the IIS logfiles found in \winnt\system32\logfiles. Specific Symptoms ----------------- Here are a few specific symptoms and suggestions for how to deal with them. Symptom: Internal Error on connecting. Suggestion: Are icpermit and icexec running? If not, an internal error may be returned. Suggestion: The cgi script may have emitted malformed headers. This would be noted in the error_log. Symptom: The error log has a "cannot exec" error for the request. Suggestion: "Cannot exec" errors in error_log can be caused by accessing a .cgi file that is a shell script but does not have #!/bin/sh as the first line. Make sure the .cx files permissions include read and execute permission for "other". Symptom: Using IE 5.0, "The page cannot be displayed" page containing the message " Cannot find server or DNS Error" is displayed. Suggestion: This can be caused by icexec or icpermit being down. You may not have enough cgi consoles defined. Symptom: A warning message similar to the following appears in the Apache error log, but the cgiCOBOL program is run correctly. [Mon Jan 24 11:01:21 2000] [warn] [client 192.168.2.106] handler "icobol-handler" not found for: /home/httpd/cgicobol/scripts/cgidemo.cx Suggestion: Apache 1.3.6 has a known problem where a bogus message like this is logged. Symptom: "Premature end of script" errors. Suggestion: This may indicate that icruncgi began running the program but encountered an error. On Apache, check the script_log for clues. Symptom: "Invalid command request from client" error in the script_log. Suggestion: This can occur if an attempt is made to run cgiCOBOL without a valid license on the server. End of readcgi