Interactive COBOL Linux Readme 5.6x                      June-2026

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 for multple 64-bit versions.
Our primary build and test environment uses Rocky Linux, which is the
free community version of Red Hat Enterprise Linux (RHEL), which
remains our standard. This includes the ln8, ln9, and ln10 releases,
which are built and tested on Rocky Linux 8, 9, and 10 respectively.

We have also added Debian builds, built on Debian 12 and 13, and Ubuntu
builds, built on Ubuntu 22 and 24. The main difference with the RHEL versions
is the location of the 64-bit shared objects. They are all 64-bit only.

The compiler versions used are (for 5.6x):
    ln8: built on Rocky Linux 8 using Red Hat gcc 8.5.0-10
    ln9: built on Rocky Linux 9 using Red Hat gcc 11.2.1-9
    ln10: built on Rocky Linux 10 using Red Hat gcc 11.2.1-9
    db12: built on Debian Linux 12 using gcc 12.2.0-14
    db13: built on Debian Linux 12 using gcc 14.2.0
    ub22: built on Ubuntu Linux 22.04 using gcc 11.4.0
    ub24: built on Ubuntu Linux 24.04 using gcc 13.3.0

The product uses dynmaic linking and ships with several shared object (.so)
liibraries of its own:

    icsys64.so.5xx   provides common 64-bit system code
    icrun64.so.5xx   provides 64-bit runtime modules (requires icsys64)
    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 icsmview 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 - 5.36,
        5.40 -


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 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 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.  If the ICOBOL system seems to be hung, it may be that a particular
    process has claimed a semaphore (a semaphore protects critical system
    data structures that must only be updated by one process at a time) and
    then got stuck without releasing it.  We used to provide a utility
    called tell_sem to detect usage of semaphores by Interactive COBOL.
    Its function has been moved to the more comprehensive utility
    icsmview.  The status of the seaphores can be shown with the
    command icsmview -G s.

    Icsmview 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 icsmview
    and if the last user (PID) is still the same then, unless the
    machine is extremely slow, 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 icsmview 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.

    Any hangs that occur, in which icsmview 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
