Interactive COBOL Unix Readme 4.40 02-June-2010 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 flavors --------------------------------- Interactive COBOL (AIX) was built under AIX 5.1 for revisions 5.x and up of AIX on RS/6000 machines including PowerPC models. Supports filesizes to 4GB with an appropriate ulimit and filesystem support. (C-ISAM support) Interactive COBOL (HP-UX10) was built under HP-UX 10.20 for all HP Series PA-RISC 1.1 and up machines running HP-UX 10.20 and up. Supports filesizes to 4GB. (Using dynamic linking) (C-ISAM support) (U/FOS support) Interactive COBOL (LINUX) was built under Red Hat Linux 7.1 (Intel) (kernel 2.4.2-20). (Using dynamic linking.) Tested on Red Hat 7.1/8.0, Red Hat Enterprise 3/4 Supports filesizes to 4GB. (This is the ln4 version). This version should be used on 2.4 kernels. (C-ISAM support) Interactive COBOL (LINUX) was built under Red Hat Enterprise 4 (Intel) (kernel 2.6.9). (Using dynamic linking.) Tested on Red Hat Enterprise 4 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 (Apple) was built under Mac OS X 10.6 for revisions 10.6.x and up of Mac OS X on x86-based Macs. Supports filesizes to 4GB with an appropriate ulimit and filesystem 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 Note: the .sl extension is used under HP-UX instead of .so, .dylib for Apple Mac OS X. Interactive COBOL on UNIX uses Semaphores and Shared Memory (sometimes called the Shared Area). The keys for these items are given below: 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 - Message Queues (initialized by ICPERMIT) -------------- ---------- 0x69637051 0x69637052 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. You should use @PRN entries when you wish to print directly to the device with no spooling. You should 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. You must 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: An ICISAM file whose name is "data$426" in the COBOL program. When you are at the UNIX shell you cannot say: iccheck data$426 (because the $4 will be stripped off and remapped to arg4.) An ICISAM file whose name is "data$abc" in the COBOL program. When you are at the UNIX shell you cannot say: 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). Please change your 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. 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. Under HP-UX, the default values are stored in the kernel using the configuration file netinet/tcp_timer.h. Under AIX, the command no can be used to display and change these values. (tcp_keepidle) Under Linux, the default values can be set in the directory /proc/sys/net/ipv4. (File tcp_keepalive_time). 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. 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 HP-UX, the default values are stored in the kernel using the configuration file netinet/tcp_timer.h. Under AIX, the command no can be used to display and change these values. (tcp_timewait) 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