Summary of DEC COBOL V2.4 September 9, 1996 File specifications: OpenVMS Alpha: SYS$HELP:COBOL024_RELEASE_NOTES.PS OpenVMS Alpha: SYS$HELP:COBOL024.RELEASE_NOTES Digital UNIX: /usr/lib/cmplrs/cobol/relnotes The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Cor- poration. Digital Equipment Corporation assumes 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. 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. 1996. All rights reserved. DEC COBOL V2.4 RELEASE NOTES i CONTENTS 1 Release Summary.......................................... 1 1.1 Version Numbers....................................... 2 1.1.1 Compiler........................................... 2 1.1.2 Run-Time Library................................... 2 1.2 Problems Corrected since DEC COBOL V2.3............... 3 1.3 Restrictions.......................................... 8 1.4 Known Problems........................................ 12 1.5 Notes on Recent Enhancements.......................... 13 1.5.1 Reformat support for national literals and characters......................................... 13 1.5.2 [OpenVMS] Better support for Oracle CDD INITIAL_VALUE...................................... 13 1.5.3 [OpenVMS] Oracle CDD /NATIONALITY=JAPAN support.... 13 2 Run-Time Library Notes................................... 14 3 Debugger Notes........................................... 15 3.1 Debugger Notes for OpenVMS Alpha...................... 15 3.1.1 Restrictions....................................... 15 3.2 Debugger Notes for Digital UNIX....................... 15 3.2.1 Features........................................... 15 3.2.2 Restrictions....................................... 16 4 Documentation Notes...................................... 19 4.1 Documentation Changes and Updates..................... 19 4.2 Summary of the DEC COBOL Documentation Set............ 21 4.3 Feedback on Our Documentation......................... 22 5 Troubleshooting Tips..................................... 23 6 Using Internet Mail for Product Feedback................. 28 iii 1 Release Summary These release notes contain important information about DEC COBOL V2.4, including a short descriptive summary of features and sections on prob- lems corrected, restrictions, known problems, recent enhancements, RTL (run-time library) notes, debugger notes, documentation notes, and trou- bleshooting tips. This release is comprised of an updated compiler, an updated RTL, and updated installation guides. Both the compiler and RTL are required in order to support the functionality and bug fixes listed within these release notes. These release notes should be made available to ALL users of DEC COBOL V2.4. The release notes include many details to help facilitate migrations from and coexistence with VAX COBOL. Additional details concerning dif- ferences between VAX COBOL and DEC COBOL appear in the DEC COBOL Ref- erence Manual and the DEC COBOL User Manual. Where a release note is specific to a particular platform, [OpenVMS] or [Digital UNIX] is used. DEC COBOL V2.4 requires one of: o OpenVMS Alpha V6.1 or higher o Digital UNIX V3.0 or higher New features and improvements in DEC COBOL V2.4 include: o INTERMED diagnostic for COMPUTE statements (see the Troubleshoot- ing Tips for more details) o Reformat support for national data o [OpenVMS] Better support for Oracle CDD initial values o [OpenVMS] /NATIONALITY=JAPAN support for Oracle CDD o 32 bug fixes (since DEC COBOL V2.3-793 SSB) 1 1.1 Version Numbers 1.1.1 Compiler The edit level number, which appears at the end of the version num- ber, reflects the number of revisions made to the compiler. The ver- sion number is printed at the top of each page of the source listing generated by the compiler. For example, if the following string ap- pears in the top line: DEC COBOL V2.4-863 then the compiler is Version V2.4, edit number 863. The version number is also displayed on Digital UNIX to stdout with the -v option. 1.1.2 Run-Time Library The version numbers for the latest run-time library images are as fol- lows: DEC COBOL RTL V2.4-109 libcob/dec$cobrtl DEC COBOL RTL V2.4-34 libots2 To verify the version of the run-time library: [OpenVMS] $ ANALYZE/IMAGE sys$library:dec$cobrtl.exe [OpenVMS] $ ANALYZE/IMAGE sys$library:libots2.exe [Digital UNIX] % what /usr/shlib/libcob.so [Digital UNIX] % what /usr/shlib/libots2.so Note that the run-time library is included with DEC COBOL V2.4. 2 1.2 Problems Corrected since DEC COBOL V2.3 This section covers both OpenVMS Alpha and Digital UNIX. Problems cor- rected which apply to a single platform are tagged with [OpenVMS] or [Digital UNIX]. If the fix involves a change in the RTL, the fix is tagged with [RTL]. The list below includes all problems fixed since DEC COBOL V2.3-793 SSB. ___________________________________________________________________ Version_______Description__________________________________________ V2.4-863 [OpenVMS] The compiler no longer ACCVIOs and now issues the following diagnostic when an attempt is made to use COPY FROM DICTIONARY and Oracle CDD is not installed: Error accessing CDD shareable image SYS$SHARE:CDDSHR.EXE - CDD not installed V2.4-863 [OpenVMS,RTL] The RTL installation procedure now installs the new RTL images with the correct file protections. V2.4-863 /ALIGN=PADDING (-align padding) and the *DC SET PADALIGN directive now properly interact with other uses of /ALIGN (-align) and other directives. See the section on Doc- umentation Notes for details. V2.4-863 /CHECK=PERFORM (-check perform) now properly resets PER- FORM ranges for inline PERFORM statements. V2.4-863 The compiler now correctly identifies (with /WARN=ALL or -warn all) cases of alphanumeric truncation in moves where the destination item has insufficient size to hold the source item. V2.4-863 A problem has been corrected with the terminal to ANSI conversion of the Reformat utility. If a non-numeric lit- eral ended (with a double-quote) at column 65 and was fol- lowed only by a single character in column 66, an extra double-quote character was inserted in the output con- tinuation line. With the fix, the continuation line con- tains only the single character which followed the lit- eral. V2.4-863 [RTL] The RTL no longer causes alignment faults when lead- ing sign separate decimal items are fetched from memory. 3 ___________________________________________________________________ Version_______Description__________________________________________ V2.4-863 [OpenVMS,RTL] If a secondary key is the current key of reference, that key is now maintained as the key of ref- erence when a REWRITE or DELETE intervenes between a START and a READ NEXT. Previously, the READ NEXT would retrieve a record as if the primary key were the key of reference. V2.4-863 The compiler no longer fails when a listing is requested and an invalid condition is given on the command line. V2.4-863 A compiler failure with /STANDARD=V3 and /OPT has been corrected. V2.4-863 The compiler now correctly produces a variable length file for a SORT or MERGE statement when the SD file has a VARY- ING clause with no DEPENDING ON phrase. V2.4-863 The compiler now correctly computes the length for a group MOVE when the destination is an elementary DISPLAY nu- meric item with SEPARATE SIGN. V2.4-863 [RTL] The RTL once again correctly handles INSPECT RE- PLACING ALL without BEFORE or AFTER when replacing a 2- character string which starts on an even byte. V2.3-831 A problem in size error testing has been fixed. This could occur when a COMPUTE statement with a SIZE ERROR phrase also contained an expression including COMP-1 or COMP- 2 data items or an expression whose complexity resulted in a compiler-generated floating point intermediate data item. The effect of the bug was that the size error con- dition was not being raised when it should have been. In addition to control not being passed to the ON SIZE ER- ROR statements, such an undetected size error condition could lead to undefined results being moved to destina- tion items. V2.3-831 A problem determining the rounding constant for certain arithmetic expressions has been fixed. This could occur when an expression involving decimal or COMP operands re- quired between 31 and 37 digits of intermediate preci- sion. The error caused a constant of 0 to be used instead of 0.5 times a suitable power of 10. Effectively, the re- sult would not be rounded when this bug occurred. 4 ___________________________________________________________________ Version_______Description__________________________________________ V2.3-831 The compiler now properly handles READ INTO when AT END and INVALID KEY are not present. Previously, if READ INTO was specified with just NOT AT END or NOT INVALID KEY, the statements following the NOT clause were not executed as needed. V2.3-831 A bug has been resolved in which undefined symbol diag- nostics were issued in a Contained program for variables which were specified as GLOBAL in the containing program. This bug occurred with the use of dashes ("-") and un- derscores ("_") in an unquoted literal in ASSIGN TO. V2.3-831 [RTL] The RTL now correctly handles X/Open command line arguments and environment variables / OpenVMS logicals when there is a size mismatch with the declared size of the user variable. V2.3-831 [OpenVMS,RTL] A runtime ACCVIO in batch with extended AC- CEPT or DISPLAY and the PROTECTED or AUTOTERMINATE op- tions has been corrected. V2.3-831 [OpenVMS] Maximum record size for /NOVFC files is now set correctly. V2.3-831 [OpenVMS] Traceback line numbers for subscript checking (/CHECK=BOUNDS) have been corrected. Previously, the line number was indeterminate due to compiler optimizations. V2.3-831 [OpenVMS] The compiler no longer fails /OPT on some at- tempts to use FUNCTION CHAR. V2.3-831 [OpenVMS,RTL] The RTL installation procedure now correctly sets the protections for the 2 RTL images DEC$COBRTL.EXE and LIBOTS2.EXE. 5 ___________________________________________________________________ Version_______Description__________________________________________ V2.3-831 [Digital UNIX] The DBMS firewall for DEC COBOL under Dig- ital UNIX has been upgraded to allow the completion of a compilation when DBMS DML syntax is encountered. Pre- viously, upon recognition of the first DBMS verb in a pro- gram the DBMS firewall had issued the DBMSDMLNYI diag- nostic and had terminated the compilation. In the cur- rent compiler, after a DBMSDMLNYI diagnostic has been is- sued the compilation will continue, so that multiple oc- currences of this diagnostic will potentially be issued in a single compilation. In addition, the SUB-SCHEMA SEC- TION of the DATA DIVISION is now flagged with the DBMS- DMLNYI diagnostic. The LD statement, being optional syn- tax in the SUB-SCHEMA SECTION, is now flagged with the SYN17 diagnostic (Invalid statement syntax). Please note: the DBMSDMLNYI diagnostic is still a fatal diagnostic, so no output object file will be produced when the com- pilation has been completed. V2.3-831 Multiple-line COPY REPLACING statements that are preceded by REPLACE statements will now compile correctly. V2.3-831 [Digital UNIX] Specifying optimization (-O) with debug- ging (-g) on the command line has been corrected to pro- vide full optimization (-O4) rather than no optimization (-O0). V2.3-831 If a condition-name is involved in a compiler diagnos- tic, the compiler now identifies the condition-name in the error instead of the verb. V2.3-831 [Digital UNIX] The compiler driver now properly processes options that take one (and only one) keyword value. V2.3-831 [Digital UNIX] The compiler driver now properly processes -map and -cross. If they are specified twice (e.g. '-map alphabetic -map declared'), now the compiler will gen- erate two maps, one of each type. Prior to this version, the last specification ('-map declared' in above exam- ple), had precedence. V2.3-831 [Digital UNIX] The compiler driver now properly supplies the default keyword of high_fips for the -flagger option if no keyword is specified. V2.3-831 [Digital UNIX] The compiler driver now detects lowercase -conditional selectors as invalid. 6 ___________________________________________________________________ Version_______Description__________________________________________ V2.3-795 The compiler has been corrected to fix problems that could occur when a COMPUTE statement with a SIZE ERROR phrase also contained a divide expression and COMP-1 or COMP- 2 data items or an expression whose complexity resulted in a compiler-generated floating point intermediate data item. ___________________________________________________________________ 7 1.3 Restrictions ___________________________________________________________________ Version_______Description__________________________________________ V2.4-863 DEC COBOL V2.4 requires OpenVMS Alpha V6.1 or higher or Digital UNIX V3.0 or higher. To obtain all relevant V2.4 bug fixes and to use all V2.4 functionality, you must use the latest DEC COBOL RTL. V2.4-863 Because of the differences in the way expressions are eval- uated in a COMPUTE between VAX COBOL and DEC COBOL, the number of divide by 0 diagnostics may vary between VAX COBOL and DEC COBOL. V2.4-863 [OpenVMS] The minimum Oracle CDD/Repository version re- quired for DEC COBOL for OpenVMS Alpha is CDD/Repository V5.3. V2.4-863 [OpenVMS] The minimum Oracle DBMS version required for DEC COBOL is Oracle DBMS V5.1A. Use of the DEC COBOL DBMS support requires the separate COBOL-DBMS license/PAK; see the DEC COBOL SPD for more information. V2.4-863 [OpenVMS] The line number reported in the debugger in a traceback with /CHECK=DECIMAL does not always report the exact line number of the error and instead gives %SYSTEM-F-DECINV, decimal invalid operand, break on unhandled exception preceding line nnn To get more details on the specific line where the /CHECK=DECIMAL error was detected, there are 2 alternatives. Use RUN/NODEBUG to obtain the correct line number if you are using Open- VMS Alpha V7.0 or higher. With OpenVMS Alpha V6.1 or higher, you can use RUN/DEBUG and SHOW CALLS to obtain the cor- rect line number where the /CHECK=DECIMAL error occurred. V2.4-863 [OpenVMS] If you mix ANSI ACCEPT statements and extended ACCEPT statements in one program, the RECALL (UP-arrow or DOWN-arrow) will not be supported for the ANSI ACCEPT statements. V2.4-863 [OpenVMS] Attempts to write before the end of data (OPEN EXTEND) when using a TZK10 drive (a quarter-inch cartridge (QIC) standard drive) result in a write append error. This is a restriction in the QIC standard. The QIC standard allows drives to write at the end of data (append) or write the entire tape from beginning of tape (BOT), but does not allow data to be written before the end of data. This restriction applies to all OpenVMS Alpha hardware platforms that support the TZK10 drive. 8 ___________________________________________________________________ Version_______Description__________________________________________ V2.4-863 [OpenVMS] The Sub-schema map is not available in the list- ing file produced by compiling a COBOL program contain- ing an Oracle DBMS subschema and using the /MAP quali- fier with Oracle CDD/Plus Version 4 or higher installed on your system. This feature is documented on pages 7- 12 thru 7-17 of the DEC COBOL DBMS Database Programming manual. The information which would have been available in the Sub-schema map can be obtained in a different for- mat from the CDO utility using the following set of com- mands. This presumes that the logical CDD$DEFAULT has been properly defined. $ DICTIONARY OPERATOR CDO> SET OUTPUT filename.extension CDO> SHO GENERIC CDD$DATABASE/FULL database-name V2.4-863 [Digital UNIX] The minimum Informix C-ISAM version re- quired for DEC COBOL is V5.00. Use of ORGANIZATION IN- DEXED in DEC COBOL requires C-ISAM. V2.4-863 [Digital UNIX] The driver inhibits the linking of an ob- ject if an error level diagnostic is encountered in a com- pilation. If you must have an executable in this situ- ation, you must build the executable in 2 steps: % cobol -c /dcobol/test/dcb1798.cob % cobol dcb1798.o V2.4-863 [Digital UNIX] The following cannot be used in a stripped image: o CANCEL o CALL dataname o cobfunc,cobcall,cobcancel o VAX COBOL compatible extended ACCEPT/DISPLAY o X/Open SCREEN SECTION V2.4-863 [Digital UNIX] CANCEL, CALL dataname, cobfunc, cobcall, and cobcancel use nlist on the main executable image. This means that these references cannot be from the main ex- ecutable image to a shared object. V2.4-863 [Digital UNIX] You must use ltf (logical tape facility) as supplied on a Digital UNIX V3.0 or higher system to initialize ANSI labeled magtapes. 9 ___________________________________________________________________ Version_______Description__________________________________________ V2.4-863 [Digital UNIX] When you compile COBOL and non-COBOL ob- jects and/or sources together, you must specify the COBOL ones before the non-COBOL ones on the command line. If you put the non-COBOL objects/sources first, the result- ing executable will contain unresolvable loader symbols and will not run. V2.4-863 [Digital UNIX] For COBOL programs to access files served from UCX file-systems, you must turn off the default file locking by using the -nolocking flag. V2.4-863 [Digital UNIX] A COBOL application will abort if it tries to ACCEPT from any device mapped to stdout or stderr, and the application will abort if it tries to DISPLAY to any device mapped to stdin. If you define the corresponding environment variables to devices other than stdout, stderr, and stdin, the above problems do not occur. V2.4-863 [Digital UNIX] There is a potential "input file reading" problem caused by a change in ULTRIX Connection Software (UCX) behavior from UCX V1.3 to V2.0. In V2.0, the ex- port option DATA_CONVERSION is turned on by default. The new behavior, as described in the UCX release notes, is as follows: When DATA_CONVERSION is on, sequential non- stream_LF files are automatically converted to stream_ LF files for READ_ONLY access. Note that the conversion is done "on-the-fly", that is, the file remains in the sequential format on disk; only the data sent to the re- mote NFS client are converted. There is a difference in the file size between the orig- inal sequential non-stream_LF file (on the server side) and the converted stream_LF file (on the client side and cached by the client). To prevent the occurrence of an "input file reading" prob- lem, ask your system manager to turn off the DATA_CONVERSION option. V2.4-863 [Digital UNIX] On a UCX-served disk, some file names are illegal that are legal in Digital UNIX; for example, "a.dat.dat". V2.4-863 [Digital UNIX] When the NFS server is an ULTRIX system, it must be running Version 4.2 or greater of the ULTRIX lock demon for your program to access files on the NFS- served disks. Otherwise, your program will hang. Supe- ruser privilege will be required to kill your process. 10 ___________________________________________________________________ Version_______Description__________________________________________ V2.4-863 [Digital UNIX] When compiling in the DEC FUSE environ- ment (using the compiler options -xref or -xref_stdout), certain COBOL programs may raise this fatal DEC FUSE di- agnostic: cobol: Severe: Fatal error -7 returned from a cross-referencing library procedure To avoid this DEC FUSE restriction, COBOL programs must adhere to this rule: Any copy file that contains a PROGRAM- ID or END PROGRAM statement for a program must contain that entire program. This restriction also applies to debugging COBOL programs with Ladebug. V2.4-863 [Digital UNIX] The DEC FUSE editor does not completely support COBOL programs with successive COPY statements where there are no intervening data item references or declarations. With these COBOL programs, the FUSE Edi- tor cannot be used to display the file for COBOL items which are clicked on from the Cross-Referencer. To work around this DEC FUSE restriction, insert an extra dec- laration between successive COPY statements in the DATA DIVISION: COPY "LIBRARY-1". 01 EXTRA-ITEM PIC X. COPY "LIBRARY-2". and insert an extra reference to a data item between suc- cessive COPY statements in the PROCEDURE DIVISION: DISPLAY "TEST 7". COPY "LIBRARY-1". move "1" to extra-item. COPY "LIBRARY-2". V2.4-863 [Digital UNIX] When a shared object is created and a COBOL main entry point (_cobol_main) is identified, there is no way to create a different _cobol_main when building the executable image when -call_shared is specified. For example, ld -shared -o util.so util1.o util2.o util3.o ... ld -call_shared -o mainprog mainprog.o subprog.o util.so ... When mainprog runs, util1 is the code that is executed. The workaround is to create mainprog.so. V2.4-863 See the section "Debugger Notes" for problems and restric- tions specific to using DEC COBOL with the OpenVMS Al- pha debugger or Ladebug. ___________________________________________________________________ 11 1.4 Known Problems ___________________________________________________________________ Version_______Description__________________________________________ V2.4-863 When an exponent has a scaling factor and both operands have the value 0, the size error condition should be raised, but the value 1 is returned instead. V2.4-863 If a COMPUTE statement with an "ON SIZE ERROR" clause has more than one divisor whose value is 0, the run-time li- brary will erroneously issue the message "cobrtl: error: divide by zero; execution continues" V2.4-863 If a non-numeric literal is continued across a line break, converting the file from terminal format to ANSI format using the reformat utility causes blanks to be inserted in the literal at the point of the line break. This can result in a literal that is longer than the PIC clause, causing a syntax error. V2.4-863 [Digital UNIX] In a divide operation in which both operands are floating point (USAGE COMP-1 or COMP-2) and both operands contain the value zero, but the optimizer is not able to determine the values at compile time, the program may ter- minate at the point of the divide operation with the fol- lowing error message: Last chance handler: ... Last chance handler: internal exception: unwinding The reason is that floating 0/0 is treated (by Alpha) as different from other instances of divide by zero. In some of these cases, the COBOL runtime signal handler is able to determine that the instruction that caused the excep- tion was a floating divide, prints the appropriate mes- sage and continues execution. When the signal handler is not able to determine the exact location of the excep- tion, the program will terminate with the above error mes- sage. V2.4-863 [OpenVMS] The LINE SEQUENTIAL file organization does not work as expected if the file is assigned to a network de- vice. V2.4-863 See the section "Debugger Notes" for problems and restric- tions specific to using DEC COBOL with the OpenVMS Al- pha debugger or Ladebug. ___________________________________________________________________ 12 1.5 Notes on Recent Enhancements 1.5.1 Reformat support for national literals and characters The Reformat utility has been enhanced to support conversion of na- tional characters data from terminal to ANSI format. 1.5.2 [OpenVMS] Better support for Oracle CDD INITIAL_VALUE An enhancement has been made to DEC COBOL for OpenVMS Alpha for Or- acle CDD INITIAL_VALUE " " when used with an alphanumeric field of any size, including field sizes from 1 to 256 bytes. The enhancement is to generate the figurative constant SPACES for the COBOL VALUE clause rather than a quoted literal string containing the number of spaces which was specified for the field length. 1.5.3 [OpenVMS] Oracle CDD /NATIONALITY=JAPAN support The CDD support implemented by the COPY FROM DICTIONARY statement has been enhanced to accept /NATIONALITY=JAPAN data. CDD fields are copied into the COBOL program with proper national data entities: national character user-defined-words, data items (PIC N), and literals (N""). This support is compatible with the CDD support in VAX COBOL. 13 2 Run-Time Library Notes The V2.4 DEC COBOL Run-Time Library included with DEC COBOL V2.4 pro- vides several bug fixes beyond DEC COBOL V2.3. You must use this up- dated RTL to obtain bug fixes identified with [RTL] in the section on Problems Corrected. 14 3 Debugger Notes 3.1 Debugger Notes for OpenVMS Alpha Please read the following release notes for information about COBOL language support in OpenVMS Alpha DEBUG V6.1-000. (Also see the ap- pendix on tools in the DEC COBOL User Manual.) If you are using a debugger newer than DEBUG V6.1-000, see the debug- ger release notes for information on corrections for some of the prob- lems listed below. 3.1.1 Restrictions Following are some restrictions with this debugger: o If you use the debugger to deposit data into Edited Picture vari- ables, an error message will be displayed and the deposit opera- tion will not be completed. The debugger session will not be com- promised, however, and may be continued after this error. The er- ror message is %DEBUG-F-BUG_CHECK, internal consistency check failure o The debugger divide operators for display numeric and packed dec- imal data items are not implemented. o When using the debugger, you may notice that variable names that contain underscores and hyphens may have been changed, under cer- tain circumstances. These problems have been corrected in the de- bugger which will be available in a release of OpenVMS Alpha af- ter V7.0. Specifically, variable names that are "local" to your COBOL pro- gram (that is, names that are not visible to other separately com- piled program modules) have any underscores changed to hyphens when reported to the debugger. Thus, the data item "A_B" can only be ref- erenced as "A-B" in a debugging session. Names that are visible to other separately compiled program mod- ules (for example, EXTERNAL items, PROGRAM-ID names, etc.), have any hyphens in their names changed to underscores when reported to the debugger. Thus, the PROGRAM-ID name "SUBR-CALL" can only be ref- erenced as "SUBR_CALL" in a debugging session. 3.2 Debugger Notes for Digital UNIX The Ladebug debugger is the preferred debugger for applications built with DEC COBOL for Digital UNIX. 3.2.1 Features The following features are supported by the Ladebug debugger: o Specifying the following items using the COBOL language syntax: - Elementary and group identifiers, including subscripting and qual- ification 15 - Numeric and non-numeric literals - Arithmetic expressions o Printing (examining values) of all COBOL datatypes is supported, using the debugger's "print" command. o Assigning new values to all datatypes is supported, using the de- bugger's "assign" command. However, there are some known problems with assigning in the debugger; see below. o Assignment may be from numeric literals or may be from other pro- gram items. o Array access is supported. (However, a bug regarding arrays of nu- meric DISPLAY or PACKED-DECIMAL (COMP-3) is fixed in Ladebug Ver- sion 3.0.16 or later). o Simple arithmetic operations are supported, However, full COBOL ex- pression evaluation is not. As an example, the following simple ad- dition is supported: (ladebug) print itema + itemb 3.2.2 Restrictions Following are some restrictions with using Ladebug with DEC COBOL pro- grams: o Some Ladebug command usage is affected by COBOL language syntax (by, for example, the fact that COBOL item names may contain hyphens). This is true only when stopped within a COBOL procedure, however. One effect of this is that expressions typed on the debugger com- mand line must include spaces around arithmetic operators like "+" and "-". o Another effect of COBOL language syntax shows up in the debugger "memory-examine" command. For example, to look at the next 10 pro- gram instructions, you would normally use this debugger command: (ladebug) ./10i which says "from the current program location" (signified by the dot), examine the next 10 program locations (10 being the count) in instruction mode (signified by the "i"). When debugging COBOL programs, you would need to issue this com- mand as follows: (ladebug) ./10 i with a space between the count and the mode indicator. o In specifying qualification of variables, only the "OF" qualifier keyword is supported, not the "IN" keyword. o Assignment to program items in the debugger: - Assigning new values to character string items (PIC X or PIC A) is not supported by this debugger. 16 - The scales of the items involved must match. For example, given these declarations: 01 itema pic 9(9)v99. 01 itemb pic 9999v99. 01 bigitem pic 9(13)v9(5). the debugger will allow assignment of the values 1.23 or 8765.22 to itema, but will not allow assignment of the value 1.2 to itema. The following debugger commands are supported because the quan- tities on both sides of the assignment operator "=" have the same scale: (ladebug) assign itema = 1.23 (ladebug) assign itema = 8765.22 (ladebug) assign itema = itemb and the following debugger commands are not supported because the quantities involved are of different scales: (ladebug) assign itema = 1.2 (ladebug) assign bigitem = itema - Items cannot be assigned values of greater precision. Using the above declarations, the following debugger command is not sup- ported, because itema has greater precision than itemb: (ladebug) assign itemb = itema - When assigning to numeric edited items, the precisions of the quantities on both sides of the assignment must be the same. If the righthand value is a literal, leading zeros must be entered. - Numeric edited items with scaling factors may print with a scal- ing factor off by 1. (This problem is fixed with Ladebug Ver- sion 3.0.16 and later.) - A numeric literal on the right side of an assignment to a dec- imal item must be between -2147483648 and +2147483647. If the receiving item has a scaling factor, this restriction still ap- plies as if the scaling factor of the receiving item were ap- plied to these boundary values. o Qualification involving more than one intervening level will pro- duce a debugger error if the intervening level is an OCCURS item. For example, 01 grp1. 05 array-group occurs 6 times. 10 array-element pic s99. In the above group, "array-element" cannot be qualified (e.g. "array- element of array-group (subscript)" will get an error). However, "array-group of grp1 (subscript)" can be specified. Also array-element can be specified without qualification. 17 o Using the above code example, there is currently a bug where the address of array-element(i) is computed incorrectly when more than one data item is present in the same structure (e.g. "array-group"). The address of element(i) should be computed using the stride value, but it is computed using the element size. Therefore, the address of array-element(i) will only be correct when the stride and the size have the same value (that is, when there is only one subor- dinate item in array-group). o Subscripting is only supported for tables of one dimension. o Reference Modification is not supported by the debugger. o Stopping program execution at a program label (paragraph or sec- tion names) is not supported by the debugger. o The debugger does not correctly evaluate COBOL condition expres- sions. o Debugging support inside COPY files is not supported. Instead, the source-line cursor will point to the line with the COPY statement during the execution of the statements inside the COPY file. (Note that multi-line COPY statements will use the last line of the COPY statement for this display.) o The "whereis" command does not permit qualification or subscript- ing. o There may be problems accessing external data items. o Ladebug does not currently support Static Parameters. Therefore, LINKAGE SECTION items that are referenced in USE or REPORT WRITER procedures are conveyed to Ladebug as local static variables rather than as parameters. This only affects debugging commands that nor- mally include a program's parameter lists (dump, where, etc.). All other debugging commands (print, assign, etc.) will work as expected. o Printing arrays of PACKED-DECIMAL (COMP-3) data items and PIC X may have problems. However, such items can be printed if they are sub- ordinate to an OCCURS group item. In that case, the structure con- taining the OCCURS clause can be printed as a workaround. 18 4 Documentation Notes 4.1 Documentation Changes and Updates ___________________________________________________________________ Version_______Description__________________________________________ V2.4-863 New versions of the DEC COBOL Installation Guide for Open- VMS Alpha Systems and the DEC COBOL Installation Guide for Digital UNIX Systems are available covering DEC COBOL V2.4. V2.4-863 The DEC COBOL Installation Guide for Digital UNIX Sys- tems includes two key updates. Digital UNIX V3.0 or higher is now required for DEC COBOL V2.4, and OTABASE105 is no longer included with the DEC COBOL kit since this sub- set (along with the libsort subset) is available on the Digital UNIX V3.0 or higher kit. V2.4-863 The DEC COBOL Reference Manual and DEC COBOL User Man- ual developed for Version 2.3 are still accurate for Ver- sion 2.4 on both both OpenVMS Alpha and Digital UNIX. Doc- umentation on several enhancements since DEC COBOL V2.3 is included in Section 1.5, Notes on Recent Enhancements. V2.4-863 In the DEC COBOL Reference Manual, the documentation for the SEARCH statement (in the PROCEDURE DIVISION) currently includes the following sentence in General Rule 2: "A SEARCH statement must execute several lines to search a multi- dimensional table." To clarify this sentence, change it as follows: "A single SEARCH statement can search only one dimension of a table; therefore, you must execute SEARCH statements repeatedly to search through a multidimensional table." 19 ___________________________________________________________________ Version_______Description__________________________________________ V2.4-863 The material below updates section 16.4 of the DEC COBOL User Manual. *DC SET ALIGNMENT - makes a new entry in the align stack which activates align with no padding *DC SET NOALIGNMENT - makes a new entry in the align stack which activates noalign. (VAX-compatible) that is, a pre- vious state of either alignment or padalign is superseded by a state of no alignment. Synonym: *DC SET NOPADALIGN *DC SET PADALIGN - makes a new entry in the align stack which activates align with padding *DC END-SET ALIGNMENT - removes the current entry from the align stack, that is, the current state of alignment is deactivated and the state of alignment reverts to the preceding entry on the stack. Synonym: *DC END-SET PADALIGN Also, the initial state of alignment in a COBOL program is determined from the presence or absence of the qual- ifier /[NO]ALIGN[=[NO]PADDING] on the compiler's command line. The command-line qualifier setting for alignment is superseded by the *DC SET ALIGNMENT and *DC SET PADALIGN compiler directives in the user's COBOL program. The align- ment setting of the command line can be restored by the use of the *DC END-SET ALIGNMENT compiler directive within the COBOL program's source text. V2.4-863 [OpenVMS] The Sub-schema map is not available in the list- ing file produced by compiling a COBOL program contain- ing an Oracle DBMS subschema and using the /MAP quali- fier with Oracle CDD/Plus Version 4 or higher installed on your system. This feature is documented on pages 7- 12 thru 7-17 of the DEC COBOL DBMS Database Programming manual. The information which would have been available in the Sub-schema map can be obtained in a different for- mat from the CDO utility using the following set of com- mands. This presumes that the logical CDD$DEFAULT has been properly defined. $ DICTIONARY OPERATOR CDO> SET OUTPUT filename.extension CDO> SHO GENERIC CDD$DATABASE/FULL database-name ___________________________________________________________________ 20 4.2 Summary of the DEC COBOL Documentation Set Depending on how you order the final product, you may receive printed copies of the following DEC COBOL manuals. The order numbers for the manuals are listed in Read Before Installing DEC COBOL V2.4. o DEC COBOL Reference Manual (Unchanged for Version 2.4) Describes the source language environment for the DEC COBOL pro- grammer. Defines the format and use of statements in the DEC COBOL language. This document highlights extensions to the 1985 ANSI COBOL Standard by color in the printed document and by shading in the Bookreader syntax diagrams. o DEC COBOL User Manual (Unchanged for Version 2.4) Describes the development and run-time environment for the DEC COBOL programmer working on OpenVMS Alpha or Digital UNIX. Describes the commands to compile, link, run, and debug COBOL pro- grams. It also explains DEC COBOL I/O, the language interface with the call- ing standard, error handling and run-time messages, using struc- tures and records, writing a condition handler, native data char- acteristics, using nonnative numeric formats, compatibility issues with VAX COBOL, and using CDD/Repository, LSE, SCA, FUSE, and the debuggers. o DEC COBOL Online Help file The online Help file presents information on the DEC COBOL command qualifiers and options. [OpenVMS] Presents the COBOL general formats and describes the data items. Describes a subset of the compiler messages and the complete set of run-time messages. o DEC COBOL Installation Guide for OpenVMS Alpha Systems Explains how to install DEC COBOL V2.4 and subsequent point releases on OpenVMS Alpha, including registering a license PAK (product au- thorization key), disk space, and other prerequisites. This installation guide is provided in PostScript form (.PS file type) and in plain ASCII form (.TXT file type) on the Layered Prod- ucts Media CD. o DEC COBOL Installation Guide for Digital UNIX Systems Explains how to install DEC COBOL V2.4 and subsequent point releases on Digital UNIX, including registering a license PAK (product au- thorization key), disk space, and other prerequisites. This installation guide is provided in PostScript form (.PS file type) and in plain ASCII form (.TXT file type) on the Layered Prod- ucts Media CD. o DEC COBOL DBMS Database Programming (Unchanged for Version 2.4) Describes how to use language elements specific to DBMS database programming. 21 This book is an adjunct to the DEC COBOL basic doc set. We have col- lected the elements specific to Oracle DBMS database programming, and concentrated them in this optional book for the convenience of programmers who write COBOL programs which access Oracle DBMS databases. You can order these documents in printed form from Digital as an en- tire kit or individually. 4.3 Feedback on Our Documentation Digital appreciates your comments. If you would like to comment about the DEC COBOL documentation, or if you should find errors in any part of it, please send the manual title, order number, and your comments by one of the following methods: o Electronic Internet mail: cobol_docs@casdoc.enet.dec.com o FAX: 603-881-0120 Attn: Languages Documentation, ZKO2-3/K35 o A letter sent to the following address: Digital Equipment Corporation Languages Documentation, ZKO2-3/K35 110 Spit Brook Road Nashua, NH 03062-2698 USA 22 5 Troubleshooting Tips If your program is not executing correctly, here are some things to do: o If you have VAX COBOL, try /STANDARD=OPENVMS_AXP. o Try /NOOPTIMIZE (-O0). o Try /CHECK (-check all). o Try /WARNINGS=ALL (-warn all). An informational diagnostic from VAX COBOL has been added to DEC COBOL V2.3-831 or higher to help identify arithmetic statements that may get different results from other COBOL compilers. The INTERMED diagnostic has the text: %COBOL-I-INTERMED, Possible truncation due to use of intermediate data item This indicates an expression for which DEC COBOL introduces a float- ing point intermediate data type. This diagnostic identifies places where floating-point arithmetic is being used instead of fixed-point arithmetic for intermediate computations. This can lead to unex- pected final results and possibly results different from VAX COBOL. A statement that triggers this diagnostic should be examined and probably rewritten using two or more simpler statements. This al- lows the user, who knows the intended ranges of values for the in- put operands, to specify the precision of intermediates, result- ing in expression evaluation that can be accomplished using fixed- point arithmetic. o If the program is using a file created on a VAX, try /NOALIGNMENT (the default for DEC COBOL on both Digital UNIX and OpenVMS Alpha). o There are two ways to help correct alignment mismatches between a DEC COBOL program and another program that are sharing a record struc- ture such as a file record structure: - /NOALIGNMENT/WARNINGS=ALL (-warn all) - /MAP=DECLARED/LIS (-map decl -list) With /NOALIGNMENT/WARNINGS=ALL (-warn all), you will receive warn- ings for all data whose allocation will change if /ALIGNMENT (-align) is used. This information can be used with the listing produced with /MAP=DECLARED/LIST (-map decl -list) to determine which records might need to be aligned in other programs that will be sharing files based on these records with unaligned data that will be aligned with /ALIGNMENT (-align). o For OpenVMS (VAX COBOL and DEC COBOL), a key in the file but not the program is not considered a mismatch, and the implementation of /CHECK=DUPLICATE_KEYS only considers this a mismatch if the key is declared both in the file and the program, and differs with re- spect to whether duplicates are allowed. For DEC COBOL for Digi- tal UNIX, without -relax_key_checking, a missing key is always con- sidered a mismatch, and with -relax_key_checking, it is not con- sidered a mismatch for the keys to differ with respect to dupli- cates. In other words, to get consistent behavior with respect to 23 duplicate key checking for all three supported platforms, specify all the keys in both the file and the program. o [OpenVMS] If the program uses floating point data from a file cre- ated on an OpenVMS VAX system with VAX COBOL, try /FLOAT=D_FLOAT. o [OpenVMS] If a file is accessed that contains G-float data, use /FLOAT=G_FLOAT; if the file contains IEEE-float data, use /FLOAT=IEEE_ FLOAT. o If the program is compiled /STANDARD=V3 (-std v3), make sure that the program does not depend on the VAX COBOL /STANDARD=V3 features that are not supported by DEC COBOL. These features can result in different behavior in the following situations: - When subscripts are evaluated in STRING, UNSTRING, and INSPECT (Format 3) statements and the REMAINDER phrase of the DIVIDE state- ment - When reference modification is evaluated in STRING, UNSTRING, and INSPECT (Format 3) statements - When the variable associated with the VARYING phrase is augmented in PERFORM... VARYING... AFTER statements (Format 4) - How PIC P digits are interpreted in some moves - When the size of variable-length tables is determined /WARNINGS=ALL (-warn all) can help you determine the effects of /STANDARD=V3 (-std v3). For full information on the VAX COBOL im- plementation of /STANDARD=V3, see Appendix B in the DEC COBOL User Manual and the appendix on qualifiers in the VAX COBOL User Man- ual. o If the program is calling or called by another module (whether the other module is written in COBOL or another language), make sure the other module is compiled using equivalent alignment and float- ing point type for any arguments passed in the calls. For example, if a C module is compiled with the C equivalent of /NOALIGNMENT (the DEC COBOL default on both Digital UNIX and Open- VMS Alpha), that is, "#pragma nomember_alignment", then a DEC COBOL module that calls or is called by that C module should be compiled with no alignment. The DEC C default is MEMBER_ALIGNMENT. For com- patibility with DEC C's "#pragma member_alignment", use /ALIGNMENT=PADDING (-align padding) or *DC SET PADALIGN . o If you encounter a problem possibly related to reserved words, use o /RESERVED_WORDS=NOXOPEN o -rsv noxopen This allows use of the X/OPEN reserved words as though they were not reserved words. 24 o When you compile a program with debugging also specify /NOOPTIMIZE to expedite your debugging session. Note that -g sets -O0 with DEC COBOL on Digital UNIX. Optimization often changes the order of ex- ecution of statements in a program, and it may keep values in reg- isters and deallocate user variables. These effects can be confus- ing when you use the debugger. On OpenVMS Alpha, a diagnostic mes- sage warns you if you compile a DEC COBOL program /DEBUG without specifying anything about optimization on the command line. o Floating point (COMP-1, COMP-2) results should not be tested for exact equality or inequality; many decimal values containing frac- tional digits cannot be represented exactly in binary floating point. Instead of testing that the value exactly equals (or does not equal) the expected result, test that the value is within some small range of the expected result. o [OpenVMS] If you are using DEC C on OpenVMS Alpha, use $ CC/STANDARD=VAXC/FLOAT=D_FLOAT or $ COBOL/FLOAT=G_FLOAT The default for DEC C on OpenVMS Alpha is /FLOAT=G_FLOAT, while the default for DEC COBOL is /FLOAT=D_FLOAT. Other languages such as DEC Pascal also have /FLOAT=G_FLOAT as the default. o [OpenVMS] If you are using /NATIONALITY=JAPAN, and you get the fol- lowing at runtime %COB-F-BUG_CHECK, internal consistency check failure make sure you are using a DEC$COBRTL.EXE that supports /NATIONALITY=JAPAN (e.g., V2.3 or higher). o [OpenVMS] On OpenVMS Alpha systems, if your application uses any of the following character attribute clauses with ACCEPT or DIS- PLAY statements: o BOLD or HIGHLIGHT o BLINKING or BLINK o UNDERLINED or UNDERLINE o REVERSED or REVERSE-VIDEO you may find that the screen scrolls unexpectedly when the termi- nal is in wrap mode and DEC COBOL displays data in the lower right corner of the screen. This behavior occurs when the data being displayed fits on the bot- tom line, but the control sequences which turn off the character attributes (and which DEC COBOL appends to the data), extend past the end of the line. The unexpected scrolling is caused by the Open- VMS Alpha terminal driver because it interprets the control sequences as normal data and performs wrapping when it reaches the end of the line. 25 Screen scrolling may also occur if your application displays es- cape sequences when the cursor is in the lower right corner of the screen. Setting the terminal to nowrap mode will solve this prob- lem, or you can adjust the cursor's position prior to displaying the escape sequence. One solution to this problem is to set the terminal to nowrap mode using $ SET TERMINAL/NOWRAP. If this is not an acceptable solution, adjust the placement and/or size of the item being accepted or dis- played. o [Digital UNIX] If your program gets the following ld failure: ld: /sbin/loader: Error: unresolvable symbol in /usr/shlib/libcob.so: _cobol_main You must call cob_init from your main C program. See the DEC COBOL User Manual p. 12-22, Interprogram Communication for additional de- tails. o [Digital UNIX] If your program is not linking correctly on Digi- tal UNIX and (for example) you get the following error: ld: Can't locate file for : -lcurses cobol: Severe: Failed while trying to link This is usually an indication of an installation problem. DEC COBOL requires that the OSFPGMR subset be installed. To see if the OSFPGMR subset is installed use the following com- mand: /usr/sbin/setld -i | grep OSFPGMR o [Digital UNIX] If you get an unexpected "file not found" error at run time, there are several things to check: - Make sure the file specification in the ASSIGN TO and VALUE OF ID clauses match exactly (uppercase/lowercase, no leading/trailing blanks, and so forth) the Digital UNIX pathname you are trying to access. - Make sure VALUE OF ID names are set up as environment variables if you had previously used VALUE OF ID to specify an OpenVMS log- ical name. - Make sure any filenames with ".DAT" are explicitly specified with ".DAT" in the ASSIGN TO and VALUE OF ID clauses (VAX or DEC COBOL on OpenVMS Systems supplies ".DAT" if no file extension is spec- ified). - Make sure you are not trying to open an INDEXED file as you would with ORGANIZATION SEQUENTIAL or ORGANIZATION RELATIVE. o [Digital UNIX] If you get an unexpected "indexed keys do not match" error at run time, make sure that you have specified all the keys just as they were specified when the file was created. 26 Consider the use of the -rkc flag if you want to specify fewer DIS- PLAY (PIC X) keys than when the file was created or change the use of DUPLICATES for one of the keys. o [Digital UNIX] VAX floating point (F,D,G floating) is not supported on Digital UNIX. 27 6 Using Internet Mail for Product Feedback If you have any comments, suggestions, questions, about DEC COBOL, please send Internet mail to: cobol_ft@packed.enet.dec.com You can report problems via Internet mail, but remember to use your regular Digital support channel if you are reporting a problem and you need a response back when the problem is resolved. 28