Micro Focus COBOL Product Release Notes Micro Focus COBOL V4.0A 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 April 1997 Software Version: Micro Focus[R] COBOL[TM] V4.0A 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 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. The relationship of the product version numbers to the internal follows: _______________________________________________________________ Product Reference Product___________________________________Number_______________ Micro Focus COBOL Developer V4.0A 2XUNK/JPB:8a.1a.12.05 Micro_Focus_OSX_V4.0A_____________________21UNK/JPO:8a.1a.12.05 This update involves a repackaging of the Micro Focus COBOL de- velopment 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 correc- tions to the products 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 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