Micro Focus COBOL Product Release Notes Micro Focus COBOL V4.1A Release Notes Contents PREFACE v 1 RELEASE SUMMARY 1 1.1 Product Set 1 1.1.1 Micro Focus COBOL V4.1A Software Developer Suite for DIGITAL UNIX 1 1.1.2 Micro Focus COBOL V4.1A Application Server for DIGITAL UNIX 2 1.2 Product Licensing 2 2 SOFTWARE NOTES 2 2.1 COBDIR and LD_LIBRARY_PATH 2 2.2 Year 2000 3 2.3 Shared Objects 3 2.4 Shared Library Notes 3 2.5 Sample Program of C and COBOL Shared Object 4 2.6 Object Oriented COBOL 6 2.7 Restrictions 6 2.8 32 vs. 64 Bit Issues 7 2.8.1 Pointer handling 8 2.8.2 Calling C programs from COBOL 8 2.9 Linker Warning Message 11 2.10 Installation Enhancement 11 2.11 Configuration Requirements 12 2.12 Documentation 12 iii ___________________________________________________________________ Preface April 1998 Software Version: Micro Focus[R] COBOL[TM] V4.1A Software Developer Suite for DIGITAL UNIX Micro Focus COBOL V4.1A 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] V4.0 This documentation contains release information for Micro Focus COBOL V4.1A 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.1A Application Server, previously referred to as 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, Application Server, 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. 1998. All rights reserved. Portions Copyright Micro Focus Ltd. 1998. 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.1A OXUNK/JPD:8a.2a.13.04 Micro_Focus_Application_Server_V4.1A______O1UNK/JPK:8a.2a.13.04 1.1 Product Set The Micro Focus product set available through DIGITAL consists of the following: 1.1.1 Micro Focus COBOL V4.1A 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.1.2 Micro Focus COBOL V4.1A Application Server for DIGITAL UNIX This product consists of Application Server V4.1A for DIGITAL UNIX, previously referred to as Operating System Extensions (OSX) 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 Application Server 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 Application Server, then an Application Server license is re- quired. The runtime system (Application Server) should then be installed on the system. Check the Micro Focus Software Product Description for the DIGITAL license order number for the Application Server. This license is required for distribu- tion 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.1 COBDIR and 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. Since the release of Micro Focus COBOL V4.1, COBDIR defaults to /usr/lib/complrs/cob. Also, please note the LD_LIBRARY_PATH environment variable setting. 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 installation of the COBOL system. 2 2.2 Year 2000 Numerous enhancements have been added with Micro Focus COBOL V4.1 in support of Year 2000. These include extended date functions. Details can be found within the product documen- tation and within the file $COBDIR/dun.1 (Documentation Update Notes). This includes a description of the intrinsic functions: DATE-TO-YYYYMMDD, DATE-TO-YYYYDDD, and YEAR-TO-YYYY as well as additional formats to the ACCEPT statement. Year 2000 compliance testing was successfully performed with Micro Focus COBOL V4.1A on DIGITAL UNIX V4.0D. 2.3 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.4 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. 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 3 2. The following command line creates a COBOL shared object containing a COBOL program that will be linked to another COBOL program: 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 . -B dynamic -lsubprog -lcprog 2.5 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: 4 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. 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 . -B dynamic -lsubprog -lcprog There will be warning messages displayed 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 5 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 2.6 Object Oriented COBOL Support for Object-oriented programming is now permanently enabled. You no longer need to switch beween object and proce- dural modes. Consequently, the proc200 and oo2proc scripts (and various support files) are no longer included. 2.7 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` Beginning with the V4.0 release of Micro Focus COBOL for Digital UNIX , there is support for the -Bstatic option used in creating COBOL executables. This support has been included on the understanding that the relevant ld support has now been in- corporated into Digital UNIX V4.0. The support of -Bstatic will allow the user to statically, dynamically, or both statically and dynamically link their applications. With the release of Micro Focus COBOL V4.1A, a restriction has been removed involving the need to specify -Bdynamic. Prior to Micro Focus COBOL V4.1A, the cob command would only search for static libraries, unless -Bdynamic was specified on the cob command line. If you examine the shared library examples earlier in these release notes, you'll see that -B dynamic is specified on the cob command line. This is no longer required, however, remains in the example for anyone creating scripts for use with multiple product versions. 6 Specification of LANG: 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.8 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 7 _______________________________________________________________ C_Data_Type___________Size_in_Bytes__________COBOL_Data_Type___ 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___________ 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.8.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.8.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: 8 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. 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 DIGIAL UNIX Alpha system or any Micro Focus system on a 32 bit processor: 9 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). 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; } 10 To create the demonstration program, enter the following com- mands: cob -xv test.c demo.cbl ./test 2.9 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 /usr/lib/cmplrs/cob/coblib/libcobol.a) 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.10 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. See the Micro Focus COBOL Installation Guide for DIGITAL UNIX for installation instructions. 11 2.11 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.12 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 Getting Started (Issue 1, August 1996) o Object COBOL User Guide (Issue 4, August 1996) o Object COBOL Character Tools (Issue 1, August 1996) o Dialog System Character Mode User Guide (Issue 5, September 1994) o Master Index & Glossary (Issue 5, August 1996) o Programmer's Guide to Writing Programs (Issue 2) o Programmer's Guide to Creating User Interfaces (Issue 2) o Programmer's Guide to File Handling (Issue 2) o Programmer's Guide to Communications (Issue 2) o OO Programming with Object COBOL (Issue 3) o DCE Programmer's Guide and Reference (Issue 1) o Compatibility Guide (Issue 3, April 1993) o Language Reference (Issue 15, May 1995) o Language Reference-Additional Topics (Issue 15, May 1995) o Error Messages (Issue 11, May 1995) 12 o Pocket Guide (Issue 9, August 1996) 13