Interactive COBOL Linux Readme 5.21x 21-Oct-2016 Introduction ------------ This readme file provides additional information that pertains to the deployment of ICOBOL on Linux. Sections in this readme include: General Information Notes and Warnings Helpful Hints General Information ------------------- Interactive COBOL for Linux is available in both 32-bit and 64-bit versions. The 32-bit version can run in both 32-bit and 64-bit environments when the appropriate 32-bit system libraries have been loaded (they are not usually loaded by default). We do not recommend installing the 32-bit version on 64-bit Linux unless it is required by your application environment. The command ldd can be used to see what shared objects an executable requires. The 64-bit version will only run in a 64-bit environment. The 64-bit version contains some 32-bit client-server components that allow a server to support a mixed mode environment. In order to use the 32-bit components, the appropriate 32-bit system libraries must be present. ICOBOL 5 for Linux is built on Centos 5.10 (Community version of Red Hat Enterprise Linux) using gcc 4.1.2 for Linux kernels 2.6.18 and up. The product uses dynmaic linking and ships with several shared object (.so) liibraries of its own. icsys32.so.5xx provides common 32-bit system code icsys64.so.5xx provides common 64-bit system code icrun32.so.5xx provides 32-bit runtime modules (requires icsys32) icrun64.so.5xx provides 64-bit runtime modules (requires icsys64) icodbc32.so provides the 32-bit ODBC driver (requires icsys32) icodbc64.so provides the 64-bit ODBC driver (requires icsys64) ICOBOL uses Message Queues, Semaphores and Shared Memory (sometimes called the Shared Area) in order to coordinate multi-user access to files and system resources. The keys for these items are given below: Message Queues (managed by ICPERMIT) -------------- ---------- 0x69637051 0x69637052 Semaphores (managed by ICEXEC) ---------- ---------- Buffer 0x69636202 Open/Close 0x69636F02 Logon/Logoff 0x69637002 Lock 0x69636C02 Shared Memory (managed by ICEXEC) -------------- ---------- 0x69636702 The ipcs utility can be used to show these entries. The ICOBOL utility tell_sem can be used to check the ICOBOL semaphore status. The following table shows the range of ICOBOL revisions that had the same shared area format and revision: 2.20 - 3.2x, 3.30 - 3.3x, 3.40 - 3.6x, 4.00 - 4.0x, 4.10 - 4.7x, 4.80 - 4.8x, 5.00 - Notes and Warnings ------------------- 1. When using both @PRN and @PCQ entries, be careful about which devices are being used. Use @PRN entries when you wish to print directly to the device with no spooling. This may be required to control the order of the printouts or for sensitive documents such as checks. As a result, you should not configure an @PRN to use a printer device that is also being used by a Linux printr spooler, such as CUPS. There is no device interlock, so ICOBOL and the Linux spooler may write data to the device at the same time, resulting in trashed printouts or undefined results. Use @PCQ entries (which typically use the Linux spooler) when the use of a spooler does not cause a problem. If you currently open "$LPT" or "$LPT1" in your COBOL program and you really want it directed to a print queue then you should build a linkfile that has "$LPT @PCQ0", "$lpt @pcq0"; and/or "$LPT1 @PCQ1", "$lpt1 @pcq1", etc. ... in it. 2. Be aware that using filenames with embedded dollar ($) signs can be troublesome because they are a special character in the Linux shell. A filename with a $ is processed as just another filename character by the ICOBOL runtime, but if that filename is passed to the shell the $ will cause the shell to interpret the name rather than use it as part of the filename. Such filenames will require you to use a quoting or escape mechanism in order to reference them from the shell or from Linux programs. Some examples: For an ICISAM file whose name is "data$426" in the COBOL program. At the Linux shell the following canNOT be used: iccheck data$426 (because the $4 will be stripped off and remapped to arg4.) For an ICISAM file whose name is "data$abc" in the COBOL program. At the Linux shell the following canNOT be used: iccheck data$abc (the $abc will be stripped off and treated as a reference to the environment variable named abc) In most cases, files named with a $ in their name cannot be printed in the printer control utility because the Linux print spooler executes scripts to print files and those scripts will also incorrectly interpret filenames with $ in the name. **** A workaround for this case is to ask for a range of **** pages, I.E., 1 - 99999 in which case the runtime will **** read the file and pipe the output into lp without **** giving lp the filename with the dollar sign(s). Consider changing programs to not build filenames with dollar ($) signs or using the link facility (ICLINK) to re-map the filenames to names without the $. 3. Interactive COBOL does not handle multi-user file sharing for files from an NFS mounted filesystem. File corruption can result. Use the ICNETD/ICIOS product to share files. 4. If ICRUN and/or ICCONFIG core dump, and ICTERM is set to terminfo, the cause may be the ncurses library. One work around to try is to set ICTERM to a different ICOBOL terminal definition. Alternatively, update the ncurses lib. 5. If you are running with SELinux enabled (a Red Hat feature) you may have to set additional security information on the ICOBOL programs and shared libraries in order for them to work properly. Since this is enabled by default on new installations, some of our users report that it prevents the shared libraries from loading. If you did not intend to run with SELinux enabled, it can be changed to work at a reduced enforcement level or it can be completely disabled. Some areas to look at: the command setenforce 0 will disable SELinux the configuration is kept in /etc/selinux/config 6. Many 64-bit Linux distributions do not install the 32-bit shared libraries by default. These must be installed in order for the 32-bit ICOBOL binaries to execute. If you get a "File not Found" error when trying to execute a 32-bit executable you will need to load those libraries as well as the 32-bit loader itself. You can use the Linux ldd command to show what libraries are needed for a particular executable: ldd icrun will show the list of shared objects. The Linux file command can also be used to classify the type of file. file icrun Under Ubuntu ------------ The packages you will need are: libc6-i386 ia32-libs Here is a link for more information: www.markusbe.com/2009/09/about-running-32-bit-programs-on-64-bit-ubuntu-and-shared-libraries/ In addition, Ubuntu for instance uses the /usr/lib32 as the default location for 32-bit shared libraries. The install/installic script may need to be updated to use that directory. Under Red Hat (or Centos) ------------------------- 32-bit libraries are not installed by default on Red Hat Enterprise Linux 6 and up. You can change this behavior by setting multilib_policy=all in /etc/yum.conf, which will enable multilib policy as a system-wide policy. The additional libraries that are needed include: glibc.i686 ncurses-libs.i686 pam.i686 (for icnetd) 7. Many newer systems also enable a firewall called iptables by default. If this machine must be accessed remotely for icnetd (7333) or icpermit (7334) services you must ensure that the needed ports are open. If you receive an error message like "Error: Connection timed out (oserr=10060): Connecting to xxxx:7333" and you are certain the hostname or IP address is correct, then you may need to check your firewall settings. From a shell prompt, run the following command to see if it is running: (as root) # /sbin/service iptables status (normal) $ sudo /sbin/service iptables status The following command can be used to list the current rules. # /sbin/iptables -L The following command can be used to open port 7333. (icnetd) # /sbin/iptables -I INPUT -p tcp --syn --destination-port 7333 -j ACCEPT ("-I" above indicates insert, "INPUT" is the policy, "-p tcp" sets the protocol to tcp, "--destination-port=7333" specifies the port, "-j ACCEPT" says to accept the connection.) The following command can be used to open port 7334. (icpermit) # /sbin/iptables -I INPUT -p tcp --syn --destination-port 7334 -j ACCEPT The following command can be used to open ports 7333 and 7334. (icpermit) # /sbin/iptables -I INPUT -p tcp --syn --destination-port 7333:7334 -j ACCEPT If it is running you should be able to do the following to disable it: # /sbin/service iptables save # /sbin/service iptables stop To Turn off firewall on boot: # chkconfig iptables off Helpful Hints ------------- 1. When using network connections (ICNETD to ICIOS, ICRUNRS, or telnet), TCP/IP Keepalives are used to detect client/server unexpected terminations. Each side of a connection will use its Keepalive time to determine when to start querying the other. NOTE: Most TCP/IP implementations default to 2 hours (7200 seconds) before the first keepalive is sent and then it generally takes 10 minutes before the connection is closed. For more information on Keepalives please see your operating system documentation. In particular tcp_keepalive_time is the amount of time in seconds that a network connection has to be "idle" before a keepalive will be sent. Next the value tcp_keepalive_probes is the number of keepalive request that will be sent before marking the connection as dead and terminating processes connected to it via a SIGHUP signal. The final value tcp_keepalive_intvl is the time in seconds between each probe. Setting the values to 30, 9, 10 respectively will cause the system to wait for 30 seconds before starting to send probes, and then it will send 9 probes at 10 second intervals before terminating the connection and sending SIGHUP signals. The default values can be set in the directory /proc/sys/net/ipv4 (File tcp_keepalive_time). 2. ICPERMIT and ICNETD use TCP to communicate to other processes via a TCP port (7334 or 7333). Sometimes when the service is terminated it will take some time before the service can be re-started even though no processes are using that port. This is happening because of a TIME_WAIT state in the TCP implementation after a CLOSE. The default time on many systems for this action is 4 minutes (240 seconds). The smallest we would recommend is 30 seconds. This parameter is usually called tcp_2msl and may reference RFC 793. To stop and restart ICPERMIT and/or ICNETD faster, the defaults can be changed via the following: The default values can be set in the directory /proc/sys/net/ipv4 (File tcp_fin_timeout). 3. The tell_sem program has been provided as a tool to detect usage of semaphores by Interactive COBOL. Tell_sem displays the semaphore key along with the last user (PID) who used the semaphore, how many users are waiting and its value. It then tries to get each semaphore, if it cannot get a particular semaphore then Interactive COBOL could be hung. Rerun TELL_SEM and if the last user (PID) is still the same then unless the machine is running VERY slowly Interactive COBOL is probably hung. In this case a kill (I.E., a kill -15 pid) should be done on the pid displayed for that semaphore to unhang the system. Rerun TELL_SEM and if it still shows that same pid then try several more kills (kill -15 pid), and then finally a (kill -9 pid). The (kill -9) should ONLY be done after at least three (kill -15)'s have been done. The (kill -9) WILL free the semaphore. Tell_sem will try to detect whether a semaphore is really hung by a single pid or the machine is just running very slow. A message will be given if the machine is just running slow. Any hangs that occur, in which tell_sem is used to help kill a job, should be reported to your supplier or ENVYR Corporation. 4. A useful program under Linux is the strace command. The strace command can be used to detect problems in interfacing with the operating system since it is able to log all of the operating system calls being made by a program. End of readlinux