 














        Micro Focus COBOL Product Release Notes





































        Micro Focus COBOL V4.0A-1 Release Notes

 








    Contents

         PREFACE                                                      v

         1     RELEASE SUMMARY                                        1
               1.1   Product Set                                      1
                     1.1.1  Micro Focus COBOL V4.0A Software
                            Developer Suite for Digital UNIX   2
                     1.1.2  Micro Focus COBOL V4.0A Application
                            Server for Digital UNIX            2
               1.2   Product Licensing                                2

         2     SOFTWARE NOTES                                         2
               2.1   LD_LIBRARY_PATH                                  3
               2.2   Shared Objects                                   3
               2.3   Shared Library Notes                             3
               2.4   Sample program of C and COBOL Shared
                     Object                                           4
               2.5   RESTRICTIONS                                     6
               2.6   32 vs. 64 bit Issues                             7
                     2.6.1  Pointer handling                   8
                     2.6.2  Calling C programs from COBOL      8
               2.7   Linker Warning Message                          11
               2.8   Unsupported Features                            11
               2.9   Installation Enhancement                        11
               2.10  Configuration Requirements                      12
               2.11  Documentation                                   12
























                                                                    iii

 




    ___________________________________________________________________

    Preface



        July 1997


        Software Version:             Micro Focus[R] COBOL[TM] V4.0A-
                                      1 Software Developer Suite for
                                      Digital UNIX
                                      Micro Focus COBOL V4.0A Application
                                      Server for Digital UNIX

        File specifications:

            /usr/lib/cmplrs/cob/relnotes
            /usr/lib/cmplrs/cob/relnotes.ps

        Operating System Supported: Digital[TM] UNIX[R] V3.2

        Additional Operating System Tested: Digital UNIX V4.0

        This documentation contains release information for Micro Focus
        COBOL V4.0A-1 Software Developer Suite which includes Micro
        Focus COBOL for Digital UNIX, Micro Focus COBOL Toolbox for
        Digital UNIX and Micro Focus Dialog System for Digital UNIX
        and contains release information for Micro Focus COBOL V4.0A
        Application Server which includes Micro Focus Operating System
        Extensions (OSX) for Digital UNIX.

        The information in this document is subject to change without
        notice and should not be construed as a commitment by Micro
        Focus or Digital Equipment Corporation. Micro Focus and Digital
        Equipment Corporation assume no responsibility for any errors
        that may appear in this document.

        The software described in this document is furnished under a
        license and may be used or copied only in accordance with the
        terms of such license.

    ____________________
      [R]  Micro Focus is a registered trademark and Micro Focus
          COBOL, Toolbox, Micro Focus Dialog System, Operating System
          Extensions, Panels Version 2 are trademarks of Micro Focus
          Limited; UNIX is a registered trademark in the United States
          and other countries licensed exclusively through X/Open
          Company Limited; X/Open is a trademark of X/Open Company

          Limited.
     [TM] DEC, Digital, and the DIGITAL logo are trademarks of Digital

          Equipment Corporation.

                                                                      v

 


    Preface


        No responsibility is assumed for the use or reliability of
        software on equipment that is not supplied by Digital Equipment
        Corporation or its affiliated companies.

                          Copyright Digital Equipment
                    Corporation. 1997. All rights reserved.
        Portions Copyright Micro Focus Ltd. 1997. All rights reserved.












































    vi

 





    1  Release Summary

        These release notes contain important information covering the
        set of Micro Focus products available through Digital Equipment
        Corporation on Digital UNIX. The documentation set for the
        Micro Focus products detail the product across platforms. These
        release notes supplement that document set with information
        specific to the product functioning on Digital UNIX as well
        as describing any limitations, restrictions and open problems.
        Because these release notes cover the set of Micro Focus prod-
        ucts available through Digital Equipment Corporation, you may
        find some information discussed relating to products you have
        not purchased.

        This release is an update to the Digital release of the Micro
        Focus COBOL product on Digital UNIX. To denote the update re-
        lease, the version of Micro Focus COBOL Developer Suite has
        changed from V4.0A to V4.0A-1. The relationship of the product
        version numbers to the internal follows:

        _______________________________________________________________
                                                  Product Reference
        Product___________________________________Number_______________

        Micro Focus COBOL Developer V4.0A-1       2XUNK/JPA:8a.1a.12.06

        Micro_Focus_OSX_V4.0A_____________________21UNK/JPO:8a.1a.12.05

    This update involves a software correction to the Micro Focus
    COBOL compiler. The update from Version 4.0 to Version 4.0A in-
    volves a repackaging of the Micro Focus COBOL development tools
    into a product known as the Micro Focus COBOL Software Developer
    Suite. Micro Focus Operating System Extensions (OSX) will also be
    referenced at times within this document as the Micro Focus COBOL
    Application Server. There are also some corrections to the prod-
    ucts within this release. Further information on corrections made
    within a release are in the following directory: $COBDIR/cdr.

    1.1  Product Set

        The Micro Focus product set available through Digital consists
        of the following:









                                                                      1

 





    1.1.1  Micro Focus COBOL V4.0A Software Developer Suite for Digital
           UNIX

        This includes the Micro Focus COBOL compilation system, base
        development tools, and runtime environment as well as the Micro
        Focus COBOL Toolbox product which extends the set of tools for
        the development of Micro Focus COBOL applications as well as
        Micro Focus Dialog System which provides the tools for creating
        character mode user interfaces.


    1.1.2  Micro Focus COBOL V4.0A Application Server for Digital UNIX

        This product consists of Operating System Extensions (OSX)
        V4.0A for Digital UNIX which is the runtime components of
        Micro Focus COBOL, Micro Focus Toolbox, and Micro Focus Dialog
        System. It provides a shell that sits on top of your operating
        system providing portability features across operating systems.
        The runtime environment provided by OSX is also provided within
        the Micro Focus COBOL Software Developer Suite. If you wish to
        distribute your compiled application to a system which does not
        have a licensed and installed compilation system or OSX, then
        an OSX license is required. The runtime system (OSX) should
        then be installed on the system. Check the Micro Focus Software
        Product Description for the Digital license order number for
        OSX. This license is required for distribution of Micro Focus
        COBOL applications.



    1.2  Product Licensing

        This version of the Micro Focus COBOL products is provided and
        licensed through Digital Equipment Corporation. Product support
        (separately purchased) is also provided through the Digital
        Equipment Corporation Customer Support Group. The Micro Focus
        product document will at times discuss channels for product
        licensing and support. You will receive your product copies and
        support through Digital Channels.



    2  Software Notes








    2

 





    2.1  LD_LIBRARY_PATH

        The environment variable COBDIR needs to be set to the location
        of the installed COBOL system. The setld installation procedure
        notes the location of installation to be /usr/lib/cmplrs/cob.
        Also, please note the LD_LIBRARY_PATH environment variable set-
        ting. The environment variable LD_LIBRARY_PATH must be set to
        where the COBOL system libraries are located (normally $COBDIR
        /coblib). This information will be displayed after the instal-
        lation of the COBOL system.


    2.2  Shared Objects

        This section contains information about shared objects in Micro
        Focus COBOL running on Digital UNIX.

        Shared libraries will allow the sharing of common code (li-
        braries) among different statically linked executables. This
        will decrease the memory requirements of applications where
        many COBOL programs are compiled to many executable modules.
        Each executable will no longer need to have a copy of its non-
        unique code.



    2.3  Shared Library Notes

        The cob command does not require any options to build shared
        objects.

        The man pages for "ld" contain further information about shared
        libraries.

                ld

        Following are some example command lines that show how to use
        shared libraries with Micro Focus COBOL.

        1. The following command line creates a COBOL program that is
        built with shared objects:

              cob -xv prog.cbl

        2. The following command line creates a COBOL shared object
        containing a COBOL program that will be linked to another COBOL
        program:




                                                                      3

 





              cob -cxv subprog.cbl
              ld -shared -o libsubprog.so subprog.o

        3. The following command line creates a COBOL program built
        with shared objects that calls a COBOL subprogram that is in a
        shared object:

              cob -xv prog.cbl -L . -lsubprog


    2.4  Sample program of C and COBOL Shared Object

        This session will help you become familiar with using the com-
        ponents of the COBOL system. Using the sample programs, you
        will learn the basic steps to compile and create shared object
        programs.

           prog.cbl:

                   procedure division.
                      display "Calling COBOL program in COBOL shared library".
                      call "subprog".
                      display "Calling C program in C shared library".
                      call "cprog".
                      stop run.

           subprog.cbl:

                   display "In COBOL shared library".

           cprog.c:

                   cprog()
                   {
                       printf ("In C shared library\n");
                   }

        1. Copy the source file prog.cbl, subprog.cbl, and cprog.c into
        one of your work directories.

        2. Enter the following commands:

              cob -xcv subprog.cbl

              cc -shared -c cprog.c

              The explanation of the cob command line is:

              cob     tells the system to check the syntax
                      and compile your source code.

              -       indicates the start of the flags that
                      you set to control compilation.

    4

 





              x     process to statically or dynamically
                    linked executable module.

              c     compile no further than statically
                    linkable shared object module (.o)

              v     set verbose mode

              Refer to the system man pages regarding cc.

        3. Creating shared objects.

              ld -shared -o libsubprog.so subprog.o

              ld -shared -o libcprog.so cprog.o

        There will be warning messages displayed after you have created
        the shared libraries. These exception handling warnings can be
        ignored.

        4. Creating the final COBOL program.

              cob -xv prog.cbl -L . -lsubprog -lcprog

        There will be warning messages display by the system linker
        regarding exception handling. Currently, Micro Focus COBOL
        does not support exception handling, so the messages produced
        from the linker can be ignored. There will be no side effect in
        producing your COBOL program.

        5. Executing the final COBOL program.

        Now that the final COBOL program has been created, you must
        ensure that your LD_LIBRARY_PATH environment variable is set.

        If you are in Bourne shell, type:

              LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH
              export LD_LIBRARY_PATH

        Note: Please ensure that your $COBDIR/coblib is in your LD_
        LIBRARY_PATH environment variable.

              ./prog

        The output of ./prog should be:

              Calling COBOL program in COBOL shared library
              In COBOL shared library
              Calling C program in C shared library
              In C shared library

                                                                      5

 





    2.5  RESTRICTIONS

        cob flag `-U`

        The cob -U flag documented in the COBOL System Reference,
        Chapter 7, page 7-12 is not supported in this release of Micro
        Focus COBOL.

        The option in this case would be to use the "-d" flag. This is
        documented in the COBOL System Reference, Chapter 7, page 7-11.
        The "-d" flag will dynamically load a symbol if the symbol is
        undefined.

        cob flag `-B`

        The V4.0 release of Micro Focus COBOL for Unix for Digital
        Alpha contains support for the -Bstatic option used in creat-
        ing COBOL executables, for those end users running this COBOL
        product under Digital Unix V4.0. This support has been in-
        cluded on the understanding that the relevant ld support has
        now been incorporated into Digital Unix V4.0. The support of
        -Bstatic in Digital Unix V4.0, will allow the user to stati-
        cally, dynamically, or both statically and dynamically link
        their applications.

        Support for -Bstatic is only available when running Micro Focus
        COBOL V4.0 for Digital Alpha under Digital Unix V4.0. This
        support is not available when running Micro Focus COBOL V4.0
        under Digital UNIX V3.2.

        The following error message will be displayed if the -Bstatic
        is invoked with Digital Unix V3.2: cob: option not supported:
        -B.

        It should be noted that the Reference and Support environment
        for Micro Focus COBOL V4.0 for the Digital Alpha is Digital
        Unix V3.2, under which this product has been developed.

        Compilation as ROOT:

        As ROOT, the use of Micro Focus COBOL to compile an application
        from source on Digital UNIX V3.2 will result in the following
        error: "FATAL ERROR-Cannot access message file".



        Specification of LANG:




    6

 





        If you use the LANG environment variable with full locale
        names, such as en_US.ISO8859-1, you may see the following error
        in compilation:

        "FATAL ERROR-Cannot access message file".

        This is a result of the Micro Focus use of short names for
        the locale names as they are listed in the $COBDIR/lang di-
        rectories. In order to avoid this issue, you may set a soft
        link from the short name to the full locale name in use. For
        example, set a soft link from en_US to en_US.ISO8859-1.


    2.6  32 vs. 64 bit Issues

        The Micro Focus COBOL product running on Digital UNIX is based
        on Micro Focus 32 bit COBOL technology. While most COBOL pro-
        grams will be unaware of the underlying architectural changes,
        there are some issues concerning the interaction between C and
        COBOL that should be highlighted.

        On a "standard" 32 bit processor, the following table details
        the equivalence of C and COBOL data types:

        _______________________________________________________________
        C_Data_Type___________Size_in_Bytes__________COBOL_Data_Type___

        char                  1 byte                 PIC X

        short                 2 bytes                PIC 9(4)COMP-5

        int                   4 bytes                PIC 9(9)COMP-5

        long                  4 bytes                PIC 9(9)COMP-5

        void*_________________4_bytes________________POINTER___________

        On the Digital UNIX operating system, the following table de-
        tails the equivalence of C and COBOL data types:

        _______________________________________________________________
        C_Data_Type___________Size_in_Bytes__________COBOL_Data_Type___

        char                  1 byte                 PIC X

        short                 2 bytes                PIC 9(4)COMP-5

        int                   4 bytes                PIC 9(9)COMP-5

        long                  8 bytes                PIC 9(18)COMP-5

        void*_________________8_bytes/4_bytes________POINTER___________

                                                                      7

 





        Please note that the physical size of C long and pointer vari-
        ables are different between a standard 32 bit architecture
        processor and the Digital UNIX Alpha architecture. It is nec-
        essary for you to ensure that any COBOL / C interaction within
        your application correctly utilizes these new data type sizes.
        Failure to correctly map these data types will result in un-
        defined results, although a fatal runtime error is the most
        likely situation when attempting to execute any such code.



    2.6.1  Pointer handling

        Within the Micro Focus COBOL system, POINTER variables are
        treated as 4 byte values to maintain compatibility with other
        Micro Focus platforms. The Micro Focus system restricts the
        addressability of C pointer variables to the lower 32 bits of
        the 8 byte field and performs a transparent mapping between the
        8 byte C definition and 4 byte COBOL definition.

        Users should be aware of the following:

        When creating COBOL structures that map directly onto C struc-
        tures, appropriate padding will need to be added to the COBOL
        definition if the structure is to be passed directly to a C
        function.

        When passing pointer variables to C code, if the POINTER value
        is passed as an argument, then it will be automatically ex-
        tended to an 8 byte value.

    2.6.2  Calling C programs from COBOL

        When calling C programs from COBOL, with the exception of the
        POINTER issue described in section 2.1.1, there are no incom-
        patibilities. Variables passed by reference (the default) will
        automatically receive an 8-byte C pointer to the data item.
        For example, the following interlanguage program will function
        unchanged on a Digital UNIX Alpha system or any Micro Focus
        system on a 32 bit processor:

        demo.cbl:

        working-storage section.
        01 test1.
             03 test1-txt pic x(4).
             03 test1-term pic x value x"00".
        linkage section.
        01 test2 usage is pointer.


    8

 





        procedure division.
        start-here.
           set address of test2 to address of test1.
           display "In COBOL".
           display "Calling C".
           move 'abcd' to test1-txt.
           call 'cprog' using test1, test2.
           display "Back in COBOL".
        stop run.

        cprog.c:

        #include <stdio.h>

        cprog(test1, test2)
        char *test1;
        char *test2;
        {
           char *ptr;

           printf ("In the C program\n");
           printf ("Test1: %s\n", test1);
           printf ("Test2: Address of COBOL ptr is 0x%x\n", test2);
           ptr = test2;
           printf ("ptr: %s\n", ptr);
           printf ("Leaving C program\n");
        }

        To create the demonstration program, enter the following com-
        mands:

          cob -iv demo.cbl
          cob -xve "" cprog.c -o demorts
          ./demorts demo.int

        Calling COBOL programs from C

        When calling COBOL programs from C, with the exception of the
        POINTER issue described in section 2.1.1, there are no incom-
        patibilities. For example, the following interlanguage program
        will function unchanged on a Digital UNIX Alpha system or any
        Micro Focus system on a 32 bit processor:

        demo.cbl:

        working-storage section.
        01 dup-newname pic x(80).
        linkage section.
        01 strlen pic 9(9) comp-5.
        01 newname pic x(80).

                                                                      9

 





        procedure division.
        entry "call_cobol" using strlen newname.
           display "Length is: " at 1001.
           display strlen at 1012.
           display "You've enter: " at 1024.
           display dup-newname at 1039.
           exit program.
        stop run.

        test.c:

        #define BUFFSZ 80
        extern int call_cobol();
        extern void cobexit();
        extern int cobprintf();
        extern int cobgetch();

        main()
        {
           int status;
           char  *num;
           char buf[BUFFSZ];
           int strlen();

           cobprintf("Enter input: ");
           get_string(buf);

           num = strlen(buf);

           if (status = call_cobol(&num, buf))
              cobexit(status);
           cobexit(status);
        }

        get_string(buffer)
        char buffer[];
        {
           int i = 0;

           while (((buffer[i] = cobgetch()) != '\n') && i < BUFFSZ)
              cobprintf("%c",buffer[i++]);
           cobprintf("\n");
           buffer[i] = 0;
        }

        To create the demonstration program, enter the following com-
        mands:

          cob -xv test.c demo.cbl
          ./test

    10

 





    2.7  Linker Warning Message

        In creating COBOL programs to be executable, a warning message
        will be output from the linker:

          Warning: Linking some objects which contain exception
          information sections and some which do not.  This may
          cause fatal runtime exception handling problems.
          (last obj encountered without exceptions was
          $COBDIR/coblib/libcobol.a)
          Warning: main defined as LABEL TEXT but is defined in
          a shared lib as a GLOBAL FUNC

        $COBDIR refers to the location of the Micro Focus COBOL system.

        This warning message will not affect the building and execution
        of COBOL programs. Currently, the Micro Focus 32-bit COBOL
        system does not support exception handling on Digital UNIX.


    2.8  Unsupported Features

        Some features in the Micro Focus V4.0 product documentation are
        discussed as available on some UNIX systems. Those product com-
        ponents that provide Graphical User Interface (GUI) support are
        not available in this release on Digital UNIX. This includes
        such Toolbox features as Panels Version 2, the GUI On-line Help
        System, and Fsview.



    2.9  Installation Enhancement

        The installation instructions for the Micro Focus product have
        been enhanced to conform to a Digital standard setld installa-
        tion. Any system manager that is familiar with the installation
        of Micro Focus COBOL on other platforms will notice some dif-
        ferences. The features of the modification include verification
        of disk space for installation, operating system version check-
        ing, the ability to deinstall the product, and an installation
        verification procedure.

        One difference is that the location for the product instal-
        lation is /usr/lib/cmplrs/cob. This is the location that the
        COBDIR environment variable should be set for product use.
        The structure under this area is unchanged and will follow any
        documented location of Micro Focus product files.




                                                                     11

 





        See the Micro Focus COBOL Installation Guide for Digital UNIX
        for installation instructions.



    2.10  Configuration Requirements

        To run successfully, your Micro Focus COBOL System requires a
        minimum of 5 Mbytes of temporary disk space for a single user.
        For any additional users, you should increase the disk space by
        the combined size of the $COBDIR/coblib/libcobol.a file and the
        COBOL source file for each user.

        The amount of temporary disk space that each user requires
        can increase significantly when SORT or MERGE operations are
        performed, as these features can create temporary work files
        related to the size of the files being sorted or merged.

        Temporary work files are put in the directory specified by
        the system-defined "TMPDIR" environment variable. If TMPDIR is
        not set, the system default temporary directory will be used
        instead (as defined by the value of "P_tmpdir" in stdio.h).

    2.11  Documentation

        Micro Focus COBOL documentation consists of the following manu-
        als, available only in hard-copy form, not on CD-ROM:

        Micro Focus COBOL Developer Suite for UNIX - QA-5S9AA-GZ


        o Micro Focus COBOL V4.0 for UNIX, Getting Started

        o Micro Focus COBOL V4.0 for UNIX, Master Index and Glossary

        o Micro Focus COBOL V4.0 for UNIX, Pocket Guide

        o Micro Focus COBOL V4.0 for UNIX, COBOL User Guide

        o Micro Focus COBOL V4.0 for UNIX, COBOL System Reference
          Volume 1

        o Micro Focus COBOL V4.0 for UNIX, COBOL System Reference
          Volume 2

        o Micro Focus Object COBOL V4.0 and COBOL V4.0, Error Messages

        o Micro Focus Object COBOL V4.0 and COBOL V4.0, Language
          Reference

        o Micro Focus Object COBOL V4.0 and COBOL V4.0, Compatibility
          Guide

        o Micro Focus Object COBOL V4.0 and COBOL V4.0, Language
          Reference - Additional Topics

    12

 





        o Micro Focus COBOL Toolbox V4.0 for UNIX, Toolbox Operating
          Guide Volume 1

        o Micro Focus COBOL Toolbox V4.0 for UNIX, Toolbox Operating
          Guide Volume 2

        o Micro Focus Dialog System V2.5, Character Mode User Guide












































                                                                     13
