Interactive COBOL Unix Readme 4.89 15-Dec-2015 Introduction ------------ This readme file provides additional information that pertains to the UNIX deployment of ICOBOL. Section in this readme include: General Information Notes and Warnings Helpful Hints General Information under UNIX ------------------------------ Interactive COBOL on UNIX is a 32-bit application that runs in both 32-bit and 64-bit environments. Interactive COBOL on UNIX flavors --------------------------------- Interactive COBOL (LINUX) was built under Red Hat Enterprise (Intel) (kernel 2.6.9). (Using dynamic linking.) Tested on various Linux distributions Supports filesizes to 4GB. (This is the ln6 version). This version should be used on 2.6 kernels and up with GLIBC 2.3 and up. (U/FOS support) Interactive COBOL on UNIX places some of its code in shared objects or shared libraries. These shared objects are used by various executables. Some of these modules are shown below: icuser.so provides the ICAPI interface (requires icsys) icodbc.so provides the ODBC support (requires icsys) icrun.so.4xx provides common runtime modules (requires icsys) icsys.so.4xx provides common system code icbltn.so (optional) provides user-defined routines for the runtime Under Linux, the command ldd can be used to see what shared objects an executable requires. Interactive COBOL on UNIX uses Message Queues, Semaphores and Shared Memory (sometimes called the Shared Area). The keys for these items are given below: Message Queues (initialized by ICPERMIT) -------------- ---------- 0x69637051 0x69637052 Semaphores (initialized by ICEXEC) ---------- ---------- Buffer 0x69636202 Open/Close 0x69636F02 Logon/Logoff 0x69637002 Lock 0x69636C02 Shared Memory (initialized by ICEXEC) -------------- ---------- 0x69636702 Revisions of the ICOBOL shared area: 2.20 - 3.2x, 3.30 - 3.3x, 3.40 - 3.6x, 4.00 - 4.0x, 4.10 - 4.7x, 4.80 - 4.8x The ipcs utility can be used to show these entries. The ICOBOL utility tell_sem can be used to check the ICOBOL semaphore status. Notes and Warnings under UNIX ----------------------------- 1. When using both @PRN and @PCQ entries, be careful about which devices are being used. In general, a printer, @PRN, should not point to a device that has a UNIX spooler also using the port. Otherwise you could get garbaged output or other undefined results. Use @PRN entries when you wish to print directly to the device with no spooling. Use @PCQ entries, which use the UNIX spooler, for reports, etc. in which you do not need to actually control the order the printout comes out on the printer. 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 could be troublesome. While in the COBOL program the runtime will handle the names correctly but any time the runtime or user must interact with the UNIX shell unintended results could happen. Some examples: For an ICISAM file whose name is "data$426" in the COBOL program. At the UNIX 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 UNIX shell the following canNOT be used: iccheck data$abc (the $abc will be stripped off and the environment value abc will be sought.) Any file in the printer control utility can not be printed in most cases because the UNIX print spooler executes scripts to print files and those scripts will also incorrectly interpret filenames with dollars ($). **** 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 at open. 3. Interactive COBOL does not handle sharing files using NFS mounted drives. File corruption can result. Use the ICNETD/ICIOS product to share files. 4. Under Linux, if ICRUN and/or ICCONFIG core dump, check to see if ICTERM is set to terminfo. If so, a work around is to, set ICTERM to a valid ICOBOL terminal definition. You can also update the ncurses lib. The problem is that the rev of the ncurses library on that machine is incorrect. It must be at least the ncurses 5 version (which shows up as ncurses.so.4.0). The previous version of ncurses (4.2) shows up as ncurses.so.4.2. (P.S. do not ask us why the rev numbers go backward??). 5. Under Red Hat Linux 7.1, the ncurses 5.2 package is shipped. ICOBOL 3.10 and 3.11 were compiled with ncurses 5.0. If you get an error at execution time like: "error while loading shared libraries: libncurses.so.4: cannot load shared object file" Then a link from libncurses.so.4 should be built to libncurses.so.5 as "ln -s libncurses.so.5 libncurses.so.4" in the "/usr/lib" directory. 6. If you are running with SELinux enabled. That is Security Enhanced Linux. (A Red Hat feature.) If you cannot load shared libraries consider disabling SELinux. Some areas to look at: command setenforce 0 /etc/selinux/config 7. Newer 64-bit Linux distributions do not load the 32-bit shared libraries by default. These must be loaded 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 and the loader. 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 examples/installic script should be updated to use that directory. Under Red Hat ------------- 32-bit libraries are not installed by default on Red Hat Enterprise Linux 6. 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-lib.i686 pam.i686 (for icnetd) 8. Under Linux, many newer systems 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 can be opened. If you are seeing an error message "Error: Connection timed out (oserr=10060): Connecting to xxxx:7333" And you are sure you are going to the correct address then you need to check your firewall. From a root shell prompt on the linux machine, run the following command to see if it is running: # /sbin/service iptables status The following command can be used to open port 7333. # /sbin/iptables -A INPUT -p tcp --syn --destination-port 7333 -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 under UNIX ------------------------ 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. Under Linux, the default values can be set in the directory /proc/sys/net/ipv4. (File tcp_keepalive_time). 2. In the default case, ICPERMIT and ICNETD use TCP to communicate to other processes via a TCP port (7334 or 7333). In these cases 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: Under Linux, 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. It can be used to detect problems in interfacing with the operating system as it will log all operating system calls. End of readunix