********************************************************** NOTICE: Previous ICOBOL 5 Beta versions should be uninstalled before installing a final ICOBOL 5. ********************************************************** GETTING STARTED WITH INTERACTIVE COBOL FOR WINDOWS -------------------------------------------------- This readme is designed to help the first time Interactive Cobol user/developer get up and running from a very basic local installation and configuration. It will describe: a) how to get the license server (ICPERMIT) started, b) how to get the executive service (ICEXEC) started, c) how to get a runtime (ICRUN) started, and d) how to do a simple compile (ICOBOL). We recommend that you familiarize yourself with our product in this way. Once you are comfortable with the basic operations, you can move to more involved setups, if desired. This information applies to ICOBOL on all Windows platforms. WHAT IS NEEDED TO START ----------------------- 1) An ICOBOL license file. The default name for this is "system.lic". This can be either a demonstration or an actual license. It should contain a runtime license, and, if you wish to use the compiler, a development license. If the license is a DEMO, then all you will need is the license file itself copied onto your machine. For an actual license, a matching parallel, USB protection device (or dongle), CPUID, or MAC address (NIC) must also be available. If using a parallel protection device, it should be attached to a parallel port on the machine. Be sure the arrows on the parallel protection device are pointing toward the computer. If using a USB protection device DO NOT ATTACH IT to the machine until AFTER the software has been installed. 2) A copy of the ICOBOL for Windows Master installer program, which can be obtained by a download from our web site (www.icobol.com or ftp.icobol.com) It will have the name winXXX.exe, where XXX is the revision number. QUESTIONS TO ANSWER BEFORE INSTALLING ------------------------------------- 1) Where do I want to install ICOBOL? For a Windows system the default location is "C:\Program Files". On a 64-bit system, the 32-bit components are installed in an x86 subfolder of the main 64-bit installation. You can choose any directory you wish, but we recommend that you keep it on the system drive. 2) Where do I have my license file (system.lic) located? This should be located outside of the installation folder. It should not be located on a mapped drive. 3) Where do I want my working directory to be? The working directory is the directory that the ICRUN shortcut will start running in. While getting started, choose a directory on a local drive. Avoid using mapped drives at this point. This will also be the default working directory for any ThinClients, although they can have a different working directory. The root of a drive usually has special security settings that often interfere with running ICOBOL, so we recommend that you avoid using the root of a drive for the working directory (especially the root of the Windows system drive). 4) Where do I want my printer queue file to be? The ICOBOL print queue file, default name "system.pq", is created the first time the executive service (ICEXEC) is started, so it is not installed by the installer. However, the installer must set the file location when it configures ICEXEC, so you will need to decide where to locate this file. We recommend a location on a local drive and to avoid using mapped drives. 5) Where do I want my configuration file to be? The ICOBOL configuration file, default name "system.cfi", is created by the installer and you will need to decide where to tell the installer to locate it. We recommend a location on a local drive that is outside of the installation folder and to avoid using a mapped drive location. The default settings in the configuration file will get you started. 6) Starting with ICOBOL 4.70, a separate directory is available for storing system files that have been customized by the user. The environment variable ICCONFIGDIR can be set to this directory. Any customized help, messages, print, or term file should be created in this directory. DOING THE INSTALLATION ---------------------- You are now ready to start the ICOBOL installation program. As mentioned, you can change the default names if you wish, but otherwise keep the default selections. Once you have finished the installation, reboot your machine. The ICOBOL services should start. The default location for the services log files is: "C:\ProgramData\ICOBOL". A shortcut is placed in the ICOBOL start-menu folder to access this folder because ProgramData is a hidden folder. Look at the files called "icpermit_YYYYMMDD.lg" or "icexec_YYYYMMDD.lg", where YYYYMMDD is a date stamp. Look for the most recent date stamp. These files should give you an idea of what any problem is. For ICPERMIT, the most likely causes at this point are a typo in the license file, a problem with the parallel port on which the dongle is attached, or the dongle is not attached properly. STARTING THE ICOBOL RUNTIME (ICRUN) ----------------------------------- The major issue to remember here is that you cannot start ICRUN without having ICPERMIT running. Attempting to do so will result in this error: connection refused (oserr=10061) Connecting to localhost:7334. If you receive this error, you need to go back to the section above on ICPERMIT. If ICPERMIT is running, then you are ready to start an ICRUN. Until you are familiar with the basics, avoid using shortcut icons for this purpose. Instead, use one or both of these methods: 1) Go to Start->All Programs->ICOBOL 5->Runtime. (On a 64-bit system, there will be a Runtime (32) and a Runtime (64)) This will start our sample logon program. 2) Open a command prompt and either go to your ICOBOL installation directory or make that directory a part of your PATH. The installer updates the PATH automatically, but that change only takes place when the user logs off and then logs back on. Then give this command: icrunw -ai If ICRUN fails to start, look for the file "icrun.lg" in the current directory. This file should indicate the source of the error. USING THE COMPILER (ICOBOL) --------------------------- Once you are familiar with Interactive COBOL, you will probably want to do your compiling from within our Integrated Development Environment (ICIDE). However, when starting out, you may wish to compile from a command line to learn about the various options. As with ICRUN, in order to use the compiler ICPERMIT must be running. The ICOBOL installation includes the source code for our logon program in the "examples\programs" subfolder. The contents of the folder can be copied to any convenient folder where you have read/write permissions. The installation folder and its subfolders will usually be read-only. Then, from a command prompt, if you givethis command: icobol -a -e -l logon.sr it would create the following files: icobol.lg - This is the log file for the compiler. It will indicate any errors in actually starting the compiler. The most likely would be a 'file not found' type of error. logon.er - This file contains any actual compilation errors. logon.ls - This is the listing file. logon.cx - The executable file. You can experiment with the various options. To try compiling some of your own programs, you will most likely need to include the -C switch to tell the compiler where to find your copy files. For example, if they are located in "c:\mycpys", just add "-C c:\mycpys" to the command line. You can give up to 16 different directories to be searched. If your source is in card format, you will need to add the "-F c" switch. In order to see all the switches and their possible settings, from a command prompt give the command: icobol -h | more ICPERMIT - ICPERMIT runs as a service to provide licensing. To find the status of ICPERMIT, go to Control Panel, ICOBOL Services. In order to use the compiler or to start a runtime, ICPERMIT must show as started. If it shows as stopped, highlight ICPERMIT and click on start. If this fails, click on Auditing, then click on View current file. This will bring up the icpermit.lg file, which should indicate any errors. If there is no icpermit.lg file available, then you probably have an access problem. Make sure that System has permission for full control access to the SystemRoot directory "C:\WINNT" or "C:\Windows", or change the location for the file to another directory. ICEXEC - ICEXEC runs as a service and serves as a process manager and coordinator for ICOBOL. In order to start an ICRUN session, ICEXEC must already be running in addition to ICPERMIT. If you attempt to start ICRUN and get an error about 'shared memory area could not be accessed', then ICEXEC is not running. As with ICPERMIT, go to ICOBOL Services under Control Panel to see the status. If it will not start, look at the log file under Auditing. If there is no Icexec.lg available, then you probably have the access problem described above under ICPERMIT. ICEXEC does not have to be running in order to use the compiler. ICEXEC manages the configuration and the printer queue. It is important to remember that any time a change is made to the configuration file, that change will not take effect until ICEXEC has been stopped and restarted. ------------------ PROBLEM RESOLUTION ------------------ E-Mail support is available at: support@icobol.com with a valid support contract. Make sure to include the exact revision of the product being used, the exact text of any error messages (a copy of the log file is the best), and the output from the running of the ICINFO program. Icinfo -a can be used to create an audit log as icinfo.lg. The standard installation will create a shortcut for icinfo that has the -a option. End of readme