HP Micro Focus Object COBOL/UX Release Notes for Version B.13.40 HP 9000 Computers on HP-UX 11.x Edition: First Edition Product Number: 5967-0046 U.S.A. Copyright 2000 Hewlett-Packard Company. Legal Notices The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this material. Including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance or use of this material. Copyright © 2000 Hewlett-Packard Company. This document contains information which is protected by copyright. All rights are reserved. Reproduction, adaptation, or translation without prior written permission is prohibited, except as allowed under the copyright laws. Corporate Offices: Hewlett-Packard Company 3000 Hanover Street. Palo Alto, California 94304 U.S.A. Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in sub-paragraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause in DFARS 252.227-7013. Rights for non-DOD U.S. Government Departments and Agencies are as set forth in FAR 52.227-19(c)(1,2). Use of this manual and flexible disc(s), compact disc(s), or tape cartridge(s) supplied for this pack is restricted to this product only. Additional copies of the programs may be made for security and back-up purposes only. Resale of the programs in their present form or with alterations, is expressly prohibited. A copy of the specific warranty terms applicable to your Hewlett-Packard product and preplacement parts can be obtained from your local Sales and Service Office. Trademarks © Copyright 1980, 1984, 1986 AT&T Technologies, Inc. UNIX and System V are registered trademarks of AT&T in the USA and other countries. UNIX® is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. © Copyright 1985-1986, 1988 Massachussetts Institute of Technology. X Window SystemTM is a trademark of the Massachussetts Institute of Technology. X/Open® is a registered trademark of the X/Open Company Limited in the UK and other countries. OSF/MotiTM is a trademark of the Open Software Foundation, Inc. in the U.S. and other countries. Certification for conformance with OSF/Motif user environment pending. AnimatorTM is a trademark of Micro Focus Ltd. ToolboxTM is a trademark of Micro Focus Ltd. GLOBEtrotterTM is a trademark of GLOBEtrotter Software, Inc. FLEXlmTM and Flexible License ManagerTM are registered trademarks of GLOBEtrotter Software, Inc. FLEXadminTM is a trademark of GLOBEtrotter Software, Inc. PostScripTM is a trademark of Adobe Systems, Inc. NetscapeTM and Netscape NavigatorTM are registered trademarks of Netscape Communications Corporation in the United States and other countries. SimpleLinkTM is a trademark of Hewlett-Packard Company. ___________________________________________________________________________ Chapter 1: New and Changed Features ___________________________________________________________________________ With your COBOL product, you may have received Release Notes for all current versions of HP Micro Focus Object COBOL/UX available on your hardware. You only need the Release Notes for HP Micro Focus Object COBOL/UX developed for your HP-UX operating system version. Ignore the other Release Notes that are not for your version of HP-UX. This release document describes HP Micro Focus Object COBOL/UX B.13.40 including new features developed by Hewlett-Packard, installation, documentation, known problems, and limitations. The information in these Release Notes supplements the information contained in the manual set. This is not a set of replacement pages. Keep these pages with your HP Micro Focus Object COBOL/UX documentation. --------------------------------------------------------------------------- NOTE: $COBDIR refers to the root path name of your COBOL installation. By default, $COBDIR is /opt/cobol/cobdir. You must set and export the environment variables COBDIR and SHLIB_PATH, even if you leave the product in the default installation location. (See "Known Problems, Limitations, and Fixes" on page 47.) To set and export the COBDIR (for the default COBOL installed location) and SHLIB_PATH environment variables, enter the following commands: $ export COBDIR=/opt/cobol/cobdir $ export SHLIB_PATH=$COBDIR/coblib --------------------------------------------------------------------------- --------------------------------------------------------------------------- NOTE: HP Micro Focus Object COBOL/UX WWW Web Site The HP Micro Focus Object COBOL/UX WWW web site has been redesigned to include documentation, support information and articles, patches, and more. For the latest information on HP Micro Focus COBOL, visit this web site at the following URL: http://www.hp.com/go/cobol --------------------------------------------------------------------------- --------------------------------------------------------------------------- 1.1 New Features ================ 1.1.1 New Micro Focus Object COBOL Version 4.1.30 ================================================= HP Micro Focus Object COBOL/UX B.13.40 provides the Micro Focus Object COBOL version 4.1.30 to Hewlett-Packard customers. This release are supported on HP9000 computers running HP-UX 11.x. Micro Focus Object COBOL, version 4.1.30 gives you the ability to compile object COBOL applications. This release includes the following new features: * Client/Server Binding (see the online Programmer's Guide to Communications) * File striping and large file handling (over 2 Gbyte) (see the chapter "Callable File Handler" in the online manual Programmer's Guide to File Handling) * New rebuild and mfsort for mFLFS (see $COBDIR/docs/rebuild.1 and mfsort.1) * NLS processing of indexed files * New online documentation set for Micro Focus Object COBOL V4.1.30 For complete information on the new and changed features of this Micro Focus Object COBOL version 4.1.30, refer to the online release documents included from Micro Focus. You will find these files in the $COBDIR/docs directory. 1.1.2 Revised Online HP Micro Focus Object COBOL/UX Programmer's Guide ====================================================================== For this release HP provides a new edition of the online version of the HP Micro Focus Object COBOL/UX ProgrammerÕs Guide. You can view and print this manual with any html browser, such as Netscape's Navigator. For more information on the documenation for this release, see the section Section 4.1.1 Locating COBOL Information 1.1.3 New ldtab Processing ========================== When a COBOL program or custom run-time system is built by cob, the COBOL run-time system symbol table (ldtab) will be optimized to: * reduce building time * reduce the amount of data space initially required by the executable * eliminate data dependencies on system libraries that could otherwise limit binary compatibility. For most users this change will only result in the benefits noted above. There are four specific cases where this change will require action to preserve or obtain previoiusly expected behavior. 1. If you use the run-time tunable mixedlang_external_check. 2. If your COBOL code references a significant number of non-COBOL external data items. 3. If you use the +p option to cob to diagnose name space problems. 4. If you use the +e option to ld. For more information, see the section, "COBOL Run-time System Symbol Table (ldtab) and cob," in Chapter 4 in the online HP Micro Focus Object COBOL/UX Programmer's Guide in $COBDIR/docs/library.htm for more information. 1.1.4 New API to Support Loading HP-UX Shared Libraries Containing COBOL Programs ======================================================================== HP Provides three API routines to support loading HP-UX shared libraries (.sl) containing one or more COBOL programs and unloading these libraries with automatic physical CANCELing of the active COBOL programs within the shared library. * CBL_HP_SH_LOAD * CBL_HP_SH_FINDSYM * CBL_HP_SH_UNLOAD Once a successful CBL_HP_SH_LOAD has occurred, COBOL programs in the shared library can be accessed through any of the following mechanisms: * COBOL call verb statement * cobcall * cobfunc * using CBL_HP_SHL_FINDSYM and then calling the program indirectly See the section "New API to Support Loading HP-UX Shared Libraries Containg COBOL Programs" in the online of the HP Micro Focus Object COBOL/UX Programmer's Guide in $COBDIR/docs/html/library.htm. --------------------------------------------------------------------------- 1.2 Removed Features ==================== 1.2.1 All Motif Functionality ============================= All Motif functionality has been removed from HP Micro Focus Object COBOL/UX, including the graphical mode version of the Dialog System and the Fileshare View utility, fsviewmot. Use fsclose to shut down a background fileshare process (fs -b). See chapter 18 in the Programmer's Guide to File Handling manual for details. 1.2.2 Support for Distributed Computing Environment (DCE) ========================================================= Micro Focus has withdrawn support for the COBOL Distributed Computing Environment (DCE), therefore the online book COBOL DCE Programmer's Guide and Reference is not supplied. 1.2.3 core_dump Run-time Tunable ================================ The HP core_dump run-time tunable is obsolete. Use the Micro Focus core_on_error>0 or signal _regime run-time tunables instead. See the section on core_dump in the online HP Micro Focus Object COBOL/UX Programmer's Guide and section 12.3 "Run-Time Tunables" in the Micro Focus online Object COBOL User Guide for information on core_on_error and signal_regime in $COBDIR/docs/html/library.htm for more information. 1.2.4 file_io_buffering Run-time Tunable ======================================== The HP file_io_buffering run-time tunable is obsolete. Use the Micro Focus file_io_buffer_mode run-time tunables instead. See the section on file_io_buffer_mode in the online HP Micro Focus Object COBOL/UX Programmer's Guide in $COBDIR/docs/html/library.htm for more information. --------------------------------------------------------------------------- 1.3 Features That May be Removed in Future Releases =================================================== 1.3.1 File Handler Utilities ============================ The Micro Focus File Handler utilities may be removed in a future release. Use the rebuild utility instead. See $COBDIR/docs/rebuild.1 for information on rebuild. 1.3.2 Run-time Support for Classic gnts ======================================= As of version B.12.25, all gnts produced will have characteristics previoiusly available only when useing the HP platform-specific snt executable form. Old-style (classic) gnts will continue to load and execute successfully, but in a future release only new gnts (shared native code files) will be supported. ___________________________________________________________________________ Chapter 2: Installation Information ___________________________________________________________________________ Read this entire chapter and these Release Notes before installing version B.13.40 of HP Micro Focus Object COBOL/UX. Immediately after installing the product, review the online documents included in $COBDIR/docs. --------------------------------------------------------------------------- 2.1 Compatibility with Previous Versions ======================================== _______________________________________________________________________________ These Types of Code can be run on Version B.13.40 If Your Code (MF V4.1.30 base on HP-UX 11.x) Was Built With ------------------------------------------------------------ This Version Compatible of COBOL Code Notes: --------------- ------------- ---------------------------------------------- B.13.2x .int, .gnt, 1. Due to the HP-UX system changes, all objects, (V4.1 base on .snt, shared libraries, and archive libraries (.o, HP-UX 11.x) shared-bound lib*.sl, lib*.a) created prior to version executables B.13.2x of COBOL cannot be relinked on HP-UX B.12.2x (lib*.sl and 11.x and are incompatible. These will need to (V4.1 base on a.out) be rebuilt. However, lib*.sl can be executed HP-UX 10.20) on this version of COBOL with a.outs created from earlier versions. B.11.2x, B.11.30 2. If you are still experiencing problems you (V4.0 base on may have to recompile, regenerate, and relink HP-UX 10.20) your code from source. B.10.xx 3. Archive-bound executables are not supported. (V3.2 base on See "Using Shared Libraries vs. Archive HP-UX 10.01 Libraries" and "Support for Binary and 10.10) Compatibility" in Chapter 4 of the online HP Micro Focus Object COBOL/UX Programmer's B.08.7x (V3.2 base on HP-UX 9.x) ------------------------------------------------------------------------------- B.11.50 .int, .gnt, 1. Archive-bound executables are not supported. (V4.0 base on .snt See "Using Shared Libraries vs. Archive HP-UX 10.30) Libraries" and "Support for Binary Compatibility" in Chapter 4 of the online HP B.12.50 Micro Focus Object COBOL/UX Programmer's (V4.1 base on Guide for more information. HP-UX 10.30) 2. Shared bound executables will need to be rebuilt, due to changes in libc. 3. If you run an HP-UX 10.30 executable and you see the unsatisfied symbol, fs_swap_debug, run the executable with the B.13.xx run-time. ------------------------------------------------------------------------------- B.09.xx (V3.1 .int, .gnt, 1. Due to the HP-UX system limitations, all base on HP-UX ,snt objects, shared libraries, and archive 10.0x) libraries (.o, lib*.sl, lib*.a) created prior to this version of COBOL cannot be relinked on B.08.1x (V3.1 this version of HP-UX and are incompatible. (V3.1 base on These will need to be rebuilt. HP-UX 9.x) 2. Shared-bound executables will need to be rebuilt, including any customized run-time systems. Customers who attempt to run Micro Focus V3.1 shared applications before rebuilding with the current version will get the following error messages: /usr/lib/dld.sl: Can't find path for shared library: libcobwin1.sl /usr/lib/dld.sl: No such file or directory If you are still experiencing problems you may have to recompile, regenerate, and relink your code from source. 3. Archive-bound executables are not supported. See "Using Shared Libraries vs. Archive Libraries" and "Support for Binary Compatibility" in Chapter 4 of the online HP Micro Focus Object COBOL/UX Programmer's Guide for more information. ------------------------------------------------------------------------------- B.07.xx .int code 1. Only .int code is compatible from version (V3.0 base on After you install this release, you HP-UX 9.x) must do the following: 1. Regenerate native code (.gnt, .snt, .o) and rebuild any shared or archive libraries. 2. Relink any customized run-time system or statically-linked executables. 3. Regenerate any .idy files if you plan to animate .int code. ------------------------------------------------------------------------------- B.06.xx or None 1. Due to changes in the Micro Focus interpreted earlier code, you must recompile, regenerate, and (V1.2 base on relink all existing programs created using HP-UX 8.x or B.6.xx or previous versions of HP Micro Focus COBOL/UX. ________________________________________________________________________________ --------------------------------------------------------------------------- 2.2 System Requirements ======================= Version B.13.40 runs only on HP-UX 11.x. Programs compiled with version B.13.40 will not run on HP-UX 10.20 or on systems that have a previous version of Micro Focus COBOL installed. Moving an earlier version of the compiler from HP-UX 10.x (or earlier) to HP-UX 11.x is not supported. To install HP Micro Focus Object COBOL/UX, you must have the following system components: * A Hewlett-Packard 9000 computer * HP-UX operating system version 11.x * HP Micro Focus Object COBOL/UX version B.13.40 * 70 Mbytes of free disk space to install and use the Developer Suite and 18 Mbytes for the Run-Time Package To use this product you must have the following: * 32 Mbytes of memory * 2 Mbyte of swap space per user in a production environment * 10 Mbytes of swap space per user in a development environment These swap space and memory requirements are minimums. For development of larger or more complex programs, the system may need to be configured with some or all of additional physical memory, additional virtual memory (maxdsiz), or additional swap space. * 5 Mbytes of temporary disk space for a single user and 2 Mbytes additional disk space for each additional 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. If you need to change where your temporary files are built, you can use the environment variable TMPDIR. For information on TMPDIR, see HP-UX Reference. --------------------------------------------------------------------------- 2.3 Installing HP Micro Focus Object COBOL/UX ============================================= After loading the HP-UX 11.x operating system, you can install your HP Micro Focus Object COBOL/UX. To install your software, run the SD-UX swinstall command. It will invoke a user interface that will lead you through the installation. --------------------------------------------------------------------------- NOTE: When running swinstall, the HP Micro Focus Object COBOL/UX products should be selected at the bundle level rather than the fileset level to assure correct installation. The names of the bundles for B.13.40 are the following: * OBJCOBOLDEV - Object COBOL Developer Suite * OBJCOBOLRT - Object COBOL Run-time After you have selected the "Mark for installation" option, if an error box pops up stating dependent filesets could not be marked, please continue. This is just a warning. --------------------------------------------------------------------------- For more information about installation procedures and related issues, refer to Managing HP-UX Software with SD-UX and other README, installation, and upgrade documentation provided or described in your HP-UX operating system packages. swinstall installs the product in the /opt/cobol/cobdir directory. The product commands are in /opt/cobol/bin. The character mode version of Dialog System is in /opt/cobol/cobdir/dialog. After you have completed installing HP Micro Focus Object COBOL/UX, you must start-up the FLEXlm license manager before you will be able to use COBOL. For information and installation directions for FLEXlm, see Chapter 3: License Management with FLEXlm and COBOL. 2.3.1 Finding the Version Numbers ================================= To find the version number of HP Micro Focus Object COBOL/UX, execute the cobrun command in /opt/cobol/bin. The HP version number is displayed on the first line of the banner, after the original product name and support number. For example: In this example, Cobol/HP-UX is the original product name, HP35326 is the support number, and B.13.40 is the HP version number for this release. Note that the letter at the end of the second line may be different than what is listed here. Cobol/HP-UX HP35326 B.13.40 Copyright Hewlett-Packard Co. 1989-2000 V4.1 revision 30 build 10/10/2 G; 31898. Run Time System OXUPK/BMB/01340L To find the corresponding Micro Focus version number for HP Micro Focus Object COBOL/UX, type $ cat $COBDIR/cobver The Micro Focus version number for Object COBOL is displayed on the screen. For example, cobol v4.1.30-e PRN=O1UPK/BMM:8b.i1.13.06 PTI=NLS PTI=Y2K shows that this version of HP Micro Focus Object COBOL/UX corresponds with Micro Focus version 4.1.30. When you run tbox, the following banner will be displayed: +---------------------------------------+ | Micro Focus Object COBOL V4.1.30 | | Integrated Development Environment | +---------------------------------------+ When you run ds, the following banner is displayed: +----------------------------------------------------------+ | Micro Focus Character Dialog System (32 bit) - V2.5.67 | +----------------------------------------------------------+ 2.3.2 Identifying Compiler Version Used with cobwhat ==================================================== Some releases of the product require users to re-compile their sources because some new versions of the run-time system will not execute an .int file that was compiled on a previous version of COBOL. The run-time system can abort while executing an .int file that has not been recompiled. cobwhat enables you to identify the version of the compiler or NCG used to create a COBOL executable form (.int, .idy, .gnt, .snt, a.out, .o, .a, .lbr or .sl). Syntax: cobwhat filenames If the extension of the filename is not recognized, cobwhat checks if the file is an executable. For COBOL executables, cobwhat will report the NCG version string. For non-COBOL executables, no NCG version string will be reported. For .int or .idy files, cobwhat will report the Micro Focus version number for the compiler. For incorrectly named .int files (for example, .snt renamed as .int), cobwhat gives the following output: ------------------------------------- filename.int is not a COBOL .int file. ------------------------------------- ________________________ B.13.40 cobwhat Examples Listed below are some cobwhat examples and sample outputs for this version of HP Micro Focus Object COBOL/UX: Example: $ cobwhat pi.int Output: -------------------------------------------------- File : pi.int Micro Focus COBOL for UNIX V4.1 revision 030 -------------------------------------------------- Example: $ cobwhat pi.gnt pi.o pi.idy Output: -------------------------------------------------- File : pi.gnt (executable) PII 00012011525083 GNB-178056000AA tcg1c ucncg 1.29 -------------------------------------------------- File : pi.o PII 00012011525083 GNB-178056000AA tcg1c ucncg 1.29 -------------------------------------------------- File : pi.idy Micro Focus COBOL for UNIX V4.1 revision 030 -------------------------------------------------- Example: $ cobwhat pi pi.snt /opt/cobol/cobdir/coblib/libcobol.sl Output: -------------------------------------------------- File : pi (executable) PII 00012011525083 GNB-178056000AA tcg1c ucncg 1.29 -------------------------------------------------- File : pi.snt PII 00012011525083 GNB-178056000AA tcg1c ucncg 1.29 -------------------------------------------------- File : /opt/cobol/cobdir/coblib/libcobol.sl (Shared Library) ADIS 00011712151241 GNB-178056000AA tcg1c ucncg 1.29 ADISDYNA 00011712154760 GNB-178056000AA tcg1c ucncg 1.29 ADISINIT 00011712155228 GNB-178056000AA tcg1c ucncg 1.29 ADISKEY 00011710342175 GNB-030056000AA tcg1c ucncg 1.29 ADISKEY2 00011712155626 GNB-178056000AA tcg1c ucncg 1.29 mFFH 00011712175654 GNB-178056000AA tcg1c ucncg 1.29 bsio 00011712194198 GNB-178056000AA tcg1c ucncg 1.29 CBLDC001 00011712192107 GNB-178056000AA tcg1c ucncg 1.29 BTR2XFH 00011712163025 GNB-178056000AA tcg1c ucncg 1.29 PANELS 00011712161217 GNB-178056000AA tcg1c ucncg 1.29 direct2 00011712210797 GNB-178056000AA tcg1c ucncg 1.29 mfconfig 00011712215035 GNB-178056000AA tcg1c ucncg 1.29 cobintfn 00011712212977 GNB-178056000AA tcg1c ucncg 1.29 cobidbcs 00011712214537 GNB-178056000AA tcg1c ucncg 1.29 _CLASS 00011710390879 GNB-075056006AA tcg1c ucncg 1.29 _CODESET 00011710391111 GNB-075056006AA tcg1c ucncg 1.29 fcossec 00011712204714 GNB-178056000AA tcg1c ucncg 1.29 CHECKFIL 00011710391335 GNB-075056006AA tcg1c ucncg 1.29 COBWIN2 00011712221794 GNB-178056000AA tcg1c ucncg 1.29 CBLDC003 00011712192426 GNB-178056000AA tcg1c ucncg 1.29 XFHNAME 00011712192724 GNB-178056000AA tcg1c ucncg 1.29 XFHLABEL 00011712193037 GNB-178056000AA tcg1c ucncg 1.29 XFHTRACE 00011712193336 GNB-178056000AA tcg1c ucncg 1.29 ESDSFH 00011712193719 GNB-178056000AA tcg1c ucncg 1.29 mfini 00011712215976 GNB-178056000AA tcg1c ucncg 1.29 FHREDIR 00011713260281 GNB-178056000AA tcg1c ucncg 1.4 -------------------------------------------------- 2.3.3 Installing the Online Documentation Files =============================================== This version of COBOL includes html (hyper-text markup language) files for both HP Micro Focus Object COBOL/UX Programmer's Guide and the Micro Focus Object COBOL manual set. These files are in a compressed format after you install COBOL. You can choose to install the HP manual, the Micro Focus manuals, or all. Syntax: $ $COBDIR/docs/html/docstool [-install|-remove] [hp|mf|all] To install these manuals, as root run the following docstool command choosing either hp, mf, or all: $ $COBDIR/docs/html/docstool -install [hp|mf|all] This script installs the online manuals in and below $COBDIR/docs/html. You can use this same script to remove the online manuals if you would like to have them removed at a later date. $ $COBDIR/docs/html/docstool -remove [hp|mf|all] You can view these files from any html browser, such as the Netscape Navigator. To view the manuals, from your browser, load the following file: $COBDIR/docs/html/library.htm This page links you to all of the available COBOL online books. 2.3.4 Copying the Product Location ================================== You can change the product location using the copy_release script described in Chapter 4 of the HP Micro Focus Object COBOL/UX Programmer's Guide. --------------------------------------------------------------------------- 2.4 Product Configuration ========================= HP Micro Focus Object COBOL/UX is already configured to run on your HP 9000. You can change the default configuration and you can control certain machine independent features, such as the message text that HP Micro Focus Object COBOL/UX displays. See the Micro Focus Object COBOL Programmer's Guide to Writing Programs, "Application Configuration System" for more information. The system administrator should make all the changes to the HP Micro Focus Object COBOL/UX default configuration. ___________________________________________________________________________ Chapter 3: License Management with FLEXlm and COBOL ___________________________________________________________________________ 3.1 Introduction to FLEXlm ========================== This version of HP Micro Focus Object COBOL/UX includes GLOBEtrotter Software's flexible license management tool, FLEXlm. FLEXlm provides a flexible and secure method of managing concurrent use license access to software from a multi-platform, heterogeneous user environment. This gives you the following benefits: * the ability to track the exact number of users that are using COBOL for audit and planning purposes * make COBOL licenses available (or float) to any user on any computer on a network instead of being tied to a specific computer. Instead, there is a pool of licenses for the network. * make use of COBOL by development teams more cost effective * purchase additional licenses based on demonstrated need instead of guesswork --------------------------------------------------------------------------- NOTE: For more information on configuring and administering FLEXlm than is provided in this chapter, refer to GLOBEtrotter's FLEXlm End User Manual, at GLOBEtrotter's web site: http://www.globetrotter.com --------------------------------------------------------------------------- 3.1.1 FLEXlm Requirements ========================= You must have the following to use FLEXlm licensing with HP Micro Focus Object COBOL Developer Suite: * A network that allows TCP/IP communication between workstations and servers. This is normally included in the HP-UX operating system. * The FLEXlm software installed on machines that will be the license servers. * A license.dat file that contains the FLEXlm file entries. To redeem your licenses and receive the license.dat file entries, follow the directions in Section 3.2.2 Redeeming Your Licenses. 3.1.2 FLEXlm Components ======================= FLEXlm has four major components: * The license manager daemon (lmgrd) The license manager daemon (lmgrd) resides on a central machine, the license server. lmgrd controls, serves, and monitors the pool of licenses available on the network under FLEXlm. It also starts and restarts the vendor daemons. You can have three license servers, using the others as redundant or backup servers in case the first one goes down. With redundant servers most, if not all, application clients will continue executing without any noticeable delay. * The vendor daemon (HPCUPLANGS) In FLEXlm, licenses are handled by running processes. There is one process for each vendor who has a FLEXlm-licensed product on the network. This process is called the vendor daemon. The vendor daemon keeps track of how many licenses are checked out, and who has them. The vendor daemon used by HP Micro Focus Object COBOL/UX is named HPCUPLANGS. * The license file (license.dat) The licensing data is stored in a text file named license.dat. The license file, created by the HP license administrator, contains information about the license server and vendor daemons on the server. The license.dat file contains SERVER and vendor DAEMON specification lines and INCREMENT lines containing information about the license client (HP Micro Focus Object COBOL/UX). * The license client (HP Micro Focus Object COBOL/UX) The license client, HP Micro Focus Object COBOL/UX, is linked with the FLEXlm Client Library that provides the communication with the license server. During execution, the license client communicates with the vendor daemon to request a license. 3.1.3 The License Request Process ================================= When you run a FLEXlm-licensed application, a license is automatically requested and the following process occurs: 1. The license client, HP Micro Focus Object COBOL/UX, finds and reads the license file to determine the license server node and port number of the license manager daemon, lmgrd. 2. The license client establishes a connection with lmgrd and requests connection to the vendor daemon specified for this license. 3. lmgrd responds to the license client with the hostname and assigned port number for the requested vendor daemon specified for this license. 4. The license client then disconnects from lmgrd and connects to the correct vendor daemon. 5. The license client requests the check out of its license from the vendor daemon and the request is either granted unconditionally (execution will continue), granted with overdraft warning (execution will continue after a delay), or denied (the license client will terminate with a licensing error). Figure: The License Request Process [Image] --------------------------------------------------------------------------- NOTE: If a license is granted, the minimal time allocated to that license is one hour. The license stays with the user for one hour after the completion of the COBOL component that requested it (for example, a compile or Animator session). This allows a user to run multiple components without losing the license. The license is tied to a particular host machine, user, and ttyname for one hour after the last use of a licensed COBOL component, and is not released if the user logs off. --------------------------------------------------------------------------- --------------------------------------------------------------------------- NOTE: HP Micro Focus Object COBOL/UX provides you with an overdraft license allotment of ten percent of the number of licenses you purchased, rounded up to the next integer. When all purchased licenses are in use, licenses will be granted from this overdraft allotment until it is exhausted. FLEXlm displays a warning message on stderr each time a license is requested from the overdraft allotment. The message indicates that overdraft licenses are in use, and the licensed component delays for 15 seconds before continuing execution. If you frequently receive these overdraft warnings, you may not have purchased enough licenses to meet your actual needs. --------------------------------------------------------------------------- --------------------------------------------------------------------------- NOTE: If all purchased and overdraft licenses are in use, any attempt to start a licensed component by a host, user, or ttyname that does not hold a license produces an error message on stderr indicating a license denial, and the component will terminate. --------------------------------------------------------------------------- --------------------------------------------------------------------------- NOTE: The following components of HP Micro Focus Object COBOL/UX are licensed: * Compiler * Animator * Toolbox * Dialog System * Editor * Menu Handler (cmenu) The run-time is not under license enforcement at this time. Therefore, applications developed with this version of HP Micro Focus Object COBOL/UX can be run on systems that do not have FLEXlm installed. --------------------------------------------------------------------------- 3.2 Installing and Setting Up the FLEXlm License Manager ======================================================== HP Micro Focus Object COBOL Developer Suite uses GLOBEtrotter's Flexible License Manager (FLEXlm version 5.12a) software to provide license enforcement for components of this suite. The HP Micro Focus Object COBOL Developer Suite utilizes floating licenses (as opposed to node, terminal, or user locked licenses) to provide the greatest flexibility. Users can utilize some or all of the licenses as floating licenses and customize these licenses to reserve, restrict, or allow access to licenses based on a variety of criteria, including access based on host machine, terminal, or user. --------------------------------------------------------------------------- NOTE: If you are updating from HP Micro Focus Object COBOL/UX version B.12.2x or B.13.2x (Micro Focus version 4.1) to this version, you can use your current FLEXlm configuration. --------------------------------------------------------------------------- ______________________ For New Installations: If this is a new installation of HP Micro Focus Object COBOL/UX, after you have installed HP Micro Focus Object COBOL Developer Suite, you will need to do the following steps to install, set up, and start FLEXlm: 1. Use the script, hpmfocdsini, to help you install and configure FLEXlm 2. Redeem your licenses 3. Create or update the license.dat file 4. Start the license manager daemon (lmgrd) --------------------------------------------------------------------------- NOTE: The default location where hpmfocdsini installs FLEXlm is in and below: /usr/local/flexlm This is the recommended installation location. All path references and examples in this document refer to this default path. If you install your FLEXlm components in a different location or if you already had a version of FLEXlm installed, please note that your FLEXlm location will be different than the examples in this document. --------------------------------------------------------------------------- 3.2.1 Installing FLEXlm with hpmfocdsini The FLEXlm software is not automatically installed when the COBOL is installed. However, the HP Micro Focus Object COBOL/UX components will not operate without it. Therefore, if you do not already have FLEXlm installed (it may have been installed with another licensed application you use), you must install FLEXlm after you install HP Micro Focus Object COBOL/UX. HP has provided the hpmfocdsini script that will help you install and configure FLEXlm. --------------------------------------------------------------------------- Important: You must run the hpmfocdsini script even if you already have FLEXlm installed. It also identifies your hostid and hostname; you need this information to redeem your licenses. --------------------------------------------------------------------------- --------------------------------------------------------------------------- NOTE: To successfully complete hpmfocdsini you must be logged in on the system(s) that will be your license server(s) as a user with sufficient capabilities to create files and subdirectories in the locations where the FLEXlm components will be installed. In many cases this will be root or superuser. The recommended location is /usr/local/flexlm. --------------------------------------------------------------------------- To start, from your shell prompt, run hpmfocdsini: $ cd /opt/cobol/cobdir $ ./hpmfocdsini This configuration script installs the FLEXlm components and provides the hostid and hostname information you will need to redeem your licenses. If you plan to set up redundant servers, the output from this script also provides basic instructions for setting them up. For more detailed information, see the GLOBEtrotter FLEXlm End User Manual at http:\\www.globetrotter.com 3.2.2 Redeeming Your Licenses ============================= With your COBOL product you received either a Software License Certificate or a License Entitlement Certificate. You will find the License File Request Form on the back of your certificate. --------------------------------------------------------------------------- NOTE: If you cannot locate these documents or have questions about FLEXlm, contact Licensing Services at: Hewlett-Packard World Wide Licensing Services California, U.S.A. Phone: 650-960-5111 fax: 650-960-5670 e-mail: hplicense@mayfield.hp.com Hours: Monday through Friday, 8am-5pm PST Grenoble, France Phone: +33.(0)4.76.14.15.29 fax: +33.(0)4.76.14.25.15 e-mail: codeword_europe@hp-france-gen1.om.hp.com Hours: Monday through Friday, 8am-5pm GMT +1 --------------------------------------------------------------------------- You can redeem your licenses by using one of the following two methods: 1. Complete the License File Request Form on the web site at: http://us-support.external.hp.com (Americas) http://europe-support.external.hp.com (Europe/Asia Pacific) When the license.dat file entries are displayed, save them as a text file on your system. This method takes about 15 minutes. 2. Fill out the License File Request Form and fax it to HP at the appropriate number for you listed on the Software License Certificate. You will receive your license.dat file entries by e-mail and fax within eight business hours. To complete the License File Request Form, you will need to know both your hostid and hostname of the license server system (or systems if you have redundant servers). The hostid and hostname were displayed by the hpmfocdsini script and a copy of the information was left in the /var/tmp/hpmfocdsini.log file that hpmfocdsini generated. --------------------------------------------------------------------------- NOTE: Note that /var/tmp/hpmfocdsini.log may reside in the following locations: * /var/tmp/hpmfocdsini.log * /tmp/hpmfocdsini.log * /usr/tmp/hpmfocdsini.log * ./hpmfocdsini.log --------------------------------------------------------------------------- If you cannot locate this information, you can run hpmfocdsini again from the system(s) that will be your license server(s) and answer lm components. Alternately, to obtain the hostname, from the server system(s) run $ uname -n and to obtain the hostid, run: $ /usr/local/flexlm/bin/lmhostid or in ksh, run: $ print $(uname -i) 16 o p | dc In the Bourne shell, run: $ echo `uname -i` 16 o p | dc 3.2.3 Creating or Updating the license.dat File =============================================== This section describes adding COBOL license file entries to the license.dat file and some common configurations. For more complex configurations, please consult the appropriate GLOBEtrotter FLEXlm documentation at their website: http://www.globetrotter.com The license.dat file must be placed on all license servers and be made available on all other computers that intend to run HP Micro Focus Object COBOL Developer Suite. The license server computers use license.dat to build the pool of licenses for users to checkout. All other computers use license.dat as a means of locating the license server(s) to request licenses. 3.2.3.1 How to Install into an Existing license.dat File ======================================================== If you are currently using FLEXlm on the server that you also intend to serve COBOL, do the following: 1. Add the DAEMON and INCREMENT lines from your License File Certificate into the existing license.dat file. Ensure that the DAEMON line precedes any INCREMENT lines. Do not add SERVER lines to your license.dat file (see Note below). ---------------------------------------------------------------------- NOTE: You can only add to an existing license.dat file if * The number of SERVER lines provided with your HP Micro Focus Object COBOL/UX licenses is the same as the number of SERVER lines in your existing license.dat file. * The same hostids appear on the corresponding SERVER lines in each file. ---------------------------------------------------------------------- 2. If you did not create or modify an options file for the hpcuplangs vendor daemon, run $ /usr/local/flexlm/bin/lmreread This causes lmgrd to re-read the changed license.dat file and update other lmgrd processes on the network. After you have done this, you can run the following to verify that the license servers have received the new license information: $ /usr/local/flexlm/bin/lmdiag hpmfcobol If this does not work, you may need to stop all of the lmgrd processes on your network and then restart them as described in the section, Section 3.2.5 Starting lmgrd (License Manager Daemon). 3. If you did change or add an options file, you will need to shutdown the lmgrd with lmdown and then restart it to cause the new options file to be read. --------------------------------------------------------------------------- NOTE: For more information on FLEXlm utilities such as lmreread and lmdown, see the section Section 3.3 FLEXlm Utilities. --------------------------------------------------------------------------- 3.2.3.2 How to Install into a New license.dat File ================================================== If HP Micro Focus Object COBOL/UX is your first FLEXlm licensed product, or you wish to keep the COBOL licensing separate from other FLEXlm licensed products, complete the following steps: 1. Copy the SERVER, DAEMON, and INCREMENT lines (in that order) from your License File Certificate into the license.dat file. The recommended location for the license.dat file is: /usr/local/flexlm/licenses/license.dat However, the file can be located anywhere that the license servers and license clients can reliably access it. Here is an example of a license file: Sample License File: SERVER emerald 30A4B6F7 7788 DAEMON HPCUPLANGS /usr/local/flexlm/vendors/HPCUPLANGS INCREMENT hpmfcobol HPCUPLANGS 1.000 1-Jan-0000 2 \ BC926DB0AFD3DCEDF257 \ OVERDRAFT=1 ck=90 ---------------------------------------------------------------------- NOTE: License servers access license.dat to determine how many licenses are available and license clients access license.dat to determine how to contact the license servers. ---------------------------------------------------------------------- ---------------------------------------------------------------------- NOTE: The server line contains a port address of 7788. You will need to change this port address if you have another FLEXlm lmgrd already using port 7788 to serve another license.dat file, or if you have to have some other process using this port. ---------------------------------------------------------------------- ---------------------------------------------------------------------- NOTE: You can verify that the license file is valid by running lmcksum: $ lmcksum -c /usr/local/flexlm/licenses/license.dat ---------------------------------------------------------------------- 2. Create and set up an options file (this is optional). The options file controls various options such as reservations and time-outs of licenses. Most users run without an options file, but you may decide you want to use some options. For more information see Section 3.2.8 Vendor Daemon Options File and the GLOBEtrotter FLEXlm End-User Manual at http://www.globetrotter.com. If you want to configure an options file in order to more precisely control your pool of floating licenses, create the following file: /usr/local/flexlm/options/hpcuplangs.opt Be sure to specify the full path of the options file as fourth field on the DAEMON line that you copied from your License File Certificate (see Section 3.2.8.3 Enabling the Vendor Options File). 3. Verify that the license.dat file and options file are readable by all users, but only writable by root. If not, change the permissions of these files with the following commands: $ chmod 644 license.dat $ chmod 644 hpcuplangs.opt 4. Set up the debug log file (this is optional). This log file contains one line for each checkout and one line for each check in. If you have a lot of license activity, this log file will grow very large. You will need to consider where to put this file and how often to delete or prune it. You can choose not to log messages if disk space is at a premium. Note that the log file should be a local file in a user-writable directory on the license server machine. The debug log file output can be switched after the daemons are running. The technique to do this involves piping the stdout of lmgrd to a shell script that appends to the file for each line. To do this, instead of the normal start-up of $ lmgrd > filename.log, start lmgrd this way: $ lmgrd | sh -c `while read line; do echo "$line" >> \ filename.log ; done' With this start-up method, the output file, filename.log, can be renamed and a new log file will be created. You could even make filename.log a symbolic link and change the value of the link to switch the log file. To run this in the background put the following lines in a startup script, called startflex: #!/bin/ksh lmgrd | sh -c 'while read line; do echo "$line" >> $1 ; done' Then start lmgrd by running this script with the following command line: $ nohup startflex filename.log & 5. Configure your server boot process to start lmgrd for this new license.dat file when the server system is booted. This process is described in the following section, Section 3.2.4 Automating Subsequent FLEXlm License Manager Start-ups. 6. Once the new license.dat and option files are ready, you can start the lmgrd daemon and specify (or default to) the new license.dat file. This process is described in section Section 3.2.5 Starting lmgrd (License Manager Daemon). 3.2.4 Automating Subsequent FLEXlm License Manager Start-ups ============================================================ You can automate the FLEXlm start-up so that lmgrd is started automatically each time the license server machine reboots. However, it is recommended that lmgrd not be run as root. Therefore, here is sample sequence of script code that can be added to the appropriate HP-UX rc file: if [ -f /usr/local/flexlm/bin/lmgrd ] then LM_LICENSE_FILE=/usr/local/flexlm/licenses/license.dat export LM_LICENSE_FILE LIC_DATA='dirname $LM_LICENSE_FILE' echo Starting FLEXlm license daemon su nonrootuser -c "/usr/local/flexlm/bin/lmgrd -c $LM_LICENSE_FILE \ >$LIC_DATA/license.log" echo Starting FLEXlm license daemon sleep 5 fi 3.2.5 Starting lmgrd (License Manager Daemon) ============================================= If you added HP Micro Focus Object COBOL Developer Suite license lines to an existing license.dat file that already serves licenses, use $ /usr/local/flexlm/bin/lmreread or restart lmgrd as you normally do. If you created a new license.dat file, start lmgrd before you use COBOL. If FLEXlm was already installed on the system, or you requested that the components be installed somewhere else, change your working directory to that location. The following example assumes the default installation directories. Start lmgrd as a ordinary user, not as a superuser. _______________ Starting lmgrd: $ cd /usr/local/flexlm/bin $ ./lmgrd -c /usr/local/flexlm/licenses/license.dat | sh -c `while read \ line; do echo "$line" >> /flexlm_logfile_path/licenses.log ; done' $ ./lmstat -a -c /usr/local/flexlm/licenses/license.dat You will see a list of vendor daemons running as well as a list of licenses by product name. If the information does not appear to be correct, check the log file for any error messages with the following command: $ cat /logfile_path/logfile --------------------------------------------------------------------------- NOTE: If you have more than one SERVER line in your license.dat file, (for example, if you are using a redundant server configuration), you need to start lmgrd on all of the machines listed on SERVER lines before lmstat will show that the licenses are available. --------------------------------------------------------------------------- 3.2.6 Setting up Client Nodes and User Environments =================================================== In order to obtain a license, every machine that will run HP Micro Focus Object COBOL/UX must be able to access the license.dat file used by FLEXlm license server. You can set up access to license.dat through a local copy or through an NFS mount. 3.2.6.1 Setting the Path with an Environment Variable ===================================================== If your license.dat file is not located in the default location (/usr/local/flexlm/licenses/license.dat), you must set and export the environment variable LM_LICENSE_FILE and assign it the value of the fully rooted path to license.dat. For example in C shell: % setenv LM_LICENSE_FILE license_file_path In Korn and Bourne shells: $ LM_LICENSE_FILE=license_file_path $ export LM_LICENSE_FILE 3.2.7 Setting the Vendor Daemon Path ==================================== The third field on the DAEMON line in the license.dat file specifies the full path to the vendor daemon used by HPCUPLANGS. The default daemon path for HPCUPLANGS is /usr/local/flexlm/vendors/HPCUPLANGS unless hpmfocdsini was told to install FLEXlm elsewhere. If you used information produced by hpmfocdsini when you redeemed your licenses, the path to HPCUPLANGS on the DAEMON line in your license.dat file should be correct. If the path on the DAEMON line is incorrect (you may have moved HPCUPLANGS to another directory after it was installed), you must correct the path on the DAEMON line before you will be able to successfully start the FLEXlm license manager and run HP Micro Focus Object COBOL/UX. 3.2.8 Vendor Daemon Options File ================================ You can customize and control use of FLEXlm licenses by using the vendor daemon options file, hpcuplangs.opt. This options file allows you to * reserve licenses for specified users or groups of users * allow or disallow use of licenses to certain users * set a longer time for retaining a license (linger) * log activity for the use of FLEXlm's optional report writer. There can only be one options file per vendor daemon and each vendor needs a separate options file. 3.2.8.1 Using Options ===================== Options not listed in this section, but listed in GLOBEtrotter's FLEXlm documentation, are disabled in this implementation. The available options are: EXCLUDE excludes specific users from checking out licenses for a particular feature. GROUP allows the specification of a group of users for use in the other commands. INCLUDE specifies users who are allowed access to a particular feature. LINGER causes a license to stay with the user for the specified time after the completion of the COBOL component that requested it. ---------------------------------------------------------------------- NOTE: Setting LINGER to a value less than the minimum of 1 hour (3600 seconds) causes the minimum value to be used. ---------------------------------------------------------------------- NOLOG allows the user to filter messages of the specified type out of the daemon's log output. REPORTLOG specifies the log file written which is suitable for use by the Enhanced User Tools report-writer available from GLOBEtrotter Software. If filename begins with a plus sign (+), the file will be opened for append; otherwise the file will be overwritten each time the daemon is started. RESERVE ensures that a license will always be available to one or more specific users on one or more specific host computer systems. Note: Any license reserved for a user is dedicated to that user. Even when that user is not actively using the license it will be unavailable to other users. However, a RESERVED license will not cause an overdraft to be reported by FLEXadmin if the license is not actually in use. ----------------------------------------------------------------------------- Important: Using INCLUDE and EXCLUDE Before you can use options to utilize licenses effectively, you must understand the options file precedence. INCLUDE and EXCLUDE statements can be combined in the same options file and control access to the same features. When doing so, keep in mind the following: * If there is only an EXCLUDE list, everyone who is not on the list will be allowed to use the feature. * If there is only an INCLUDE list, only those users on the list will be allowed to use the feature. * If neither list exists, then everyone is allowed to use the feature. * The EXCLUDE has precedence over the INCLUDE list; so someone who is on both lists will not be allowed to use the feature. Once you create an INCLUDE or EXCLUDE list, everyone else is implicitly "outside" the group. This feature allows you, as an administrator, the ability to control licenses without having to explicitly list each user that you wish to allow having to explicitly list each user that you wish to allow or deny access to. ----------------------------------------------------------------------------- 3.2.8.2 Creating the Vendor Options File ======================================== Using any text editor, create an options file with the appropriate options described in Section 3.2.8.1 Using Options. You can put the options file anywhere; however, the recommended path for the options file is the following: /usr/local/flexlm/options/hpcuplangs.opt A vendor daemon options file consists of lines in the following format: RESERVE number feature {USER|HOST|DISPLAY|GROUP} name INCLUDE feature {USER|HOST|DISPLAY|GROUP} name EXCLUDE feature {USER|HOST|DISPLAY|GROUP} name GROUP groupname list_of_users NOLOG {IN|OUT|DENIED|QUEUED} REPORTLOG filename Lines beginning with the pound sign (#) are ignored and can be used as comments. For example, in this options file, RESERVE 1 hpmfcobol USER pat RESERVE 3 hpmfcobol USER lisa RESERVE 1 hpmfcobol HOST chaucer EXCLUDE hpmfcobol USER joe NOLOG QUEUED reserves a copy of feature hpmfcobol for user pat, 3 copies for user lisa, and a copy for anyone on a computer with the hostname of chaucer, and causes QUEUED messages to be omitted from the log file. In addition, user joe is not allowed to use the feature hpmfcobol. 3.2.8.3 Enabling the Vendor Options File ======================================== You must now enable the HPCUPLANGS vendor daemon to look at your options file. To accomplish this, add the complete path name of the options file in the license file as the fourth field on the DAEMON line for the vendor daemon, HPCUPLANGS. For example: DAEMON HPCUPLANGS /usr/local/flexlm/vendors/HPCUPLANGS \ /usr/local/flexlm/options/hpcuplangs.opt Whenever you change the fourth field on the DAEMON line in the license.dat file or you change or add an options file, you will need to shutdown the lmgrd with lmdown and then restart it to cause the new options file to be read. 3.2.9 Obtaining Additional Licenses =================================== To purchase more licenses, contact your HP Sales Representative or Order Coordinator and request the additional licenses. HP Licensing Services will provide you with a license file that contains a new INCREMENT line for the new licenses. Since the INCREMENT lines are cumulative, you can add the new INCREMENT line to your existing license file (if the SERVER and DAEMON lines are identical) as described in the section Section 3.2.3 Creating or Updating the license.dat File. --------------------------------------------------------------------------- 3.3 FLEXlm Utilities ==================== When hpmfocdsini installs the FLEXlm components, it installs the license administration tool, lmutil. lmutil contains several utility programs embedded within it. You can use these utilities to better manage the use of FLEXlm licenses. By default, the utilities are placed in /usr/local/flexlm/bin. However, they may be elsewhere if FLEXlm was already present on the system, or if hpmfocdsini was directed to install FLEXlm at an alternate location. You can access these utilities two different ways. You can use lmutil to run the utility: $ cd /usr/local/flexlm/bin $ ./lmutil utility_name Or you can run the utility directly: $ ./utility_name For example, the following two commands are equivalent: $ ./lmutil lmstat -a $ ./lmstat -a The utilities included in lmutil are the following: * lmcksum * lmdiag * lmdown * lmhostid * lmremove * lmreread * lmstat * lmswitchr * lmver All of the utilities accept the following arguments: -v print version and exit -c license_file operate on the license.dat file specified by license_file Brief descriptions of the utilities are included in the following sections. Complete information on the use of FLEXlm tools and utilities can be found in the GLOBEtrotter FLEXlm End User Manual at: http://globetrotter.com/manual.htm 3.3.1 Using lmcksum =================== This utility performs a checksum of a license file. This is useful to verify data entry errors in your license file. lmcksum prints a line-by-line checksum for the file as well as an overall file checksum. lmcksum takes the -k switch to force the encryption key checksum to be case-sensitive. lmcksum ignores all fields that do not enter into the encryption key computation. Therefore, the SERVER name and port number, as well as the DAEMON pathname and options file names are not checksummed. In addition, lmcksum will treat non-case-sensitive fields correctly (in general, lmcksum is not case-sensitive). lmcksum takes an optional DAEMON name; if specified, only license file lines for the selected DAEMON are used to compute the checksums. By default, lmcksum operates on license.dat in the current directory. Specify -c license_file if you want to checksum another license file. lmcksum Sample Output: lmcksum - Copyright (C) 1989, 1993 Globetrotter Software, Inc. lmcksum: using license file "/usr/local/flexlm/licenses/license.dat" 189: SERVER emerald 30A4B6F7 7788 166: DAEMON HPCUPLANGS /usr/local/flexlm/vendors/HPCUPLANGS 8: INCREMENT f1 demo 1.000 01-jan-0000 0 3B5CD33OE5E1G8W3AICP "" 30A4B6F7 109: (overall file checksum) 3.3.2 Using lmdiag ================== This utility allows you to diagnose problems encountered when trying to check out a license. Its usage is as follows: lmdiag [-c license_file] [-n] [feature] where -c license_file is the path to the license.dat file that contains the features you are having trouble with. -n run in non-interactive mode. lmdiag will not prompt for any input. Extended connection diagnostics are not available. feature diagnose this feature only. The lmdiag utility operates on all of the features specified in all license files found in your path. It prints information about each license and attempt to check them out. lmdiag indicates whether the checkout attempt succeeded or failed. If the checkout fails, the reason is given. If the reason for failure is that lmdiag is unable to comment to the license server, it gives you the option of running extended connection diagnostics. Extended connection diagnostics attempt to connect to each port on the license server nodes(s) and will indicate if the port number specified in the license.dat file is incorrect. lmdiag indicates each port number that is listening and indicates if it is a lmgrd process. If the vendor daemon for the feature being tested is found, lmdiag indicates the correct port number to use in the license.dat file to solve the problem. 3.3.3 Using lmdown ================== This utility allows for the graceful shutdown of all license daemons (both lmgrd and vendor daemons) on all nodes. Its usage is as follows: lmdown [-c license_file] where -c license_file specifies the license.dat file to operate on. If a license file is not specified with the -c option, lmdown operates on the license file specified by the LM_LICENSE_FILE environment variable. If a LM_LICENSE_FILE environment variable is not found, it tries to use /usr/local/flexlm/licenses/license.dat. In most cases, specify the exact location of the license.dat file you want lmdown to operate on. You usually only need to shutdown and restart licensing if you have changed a vendor daemon options file. -------------------------------------------------------------------------- Important: When shutting down redundant servers, there is a one minute delay before the servers shut down. Never use kill -9 to shut down the license servers. -------------------------------------------------------------------------- -------------------------------------------------------------------------- Important: Restricting the use of lmdown and lmremove Since lmdown shuts down the FLEXlm licensing, thereby removing the licenses from active processes, it is advisable that the system administrator restrict its use to license administrators only. This can be accomplished by starting lmgrd with the -p -2 option. This will cause lmgrd to allow only a member of the UNIX "lmadmin" group to execute lmdown, lmremove, or lmreread commands. If the UNIX group "lmadmin" does not exist, then only a member of group 0 will be allowed access to these commands. If you want to completely disable the lmdown and lmremove utilities, start lmgrd with the -x option. -------------------------------------------------------------------------- 3.3.4 Using lmhostid ==================== This utility can be used to identify the correct hostid value (that must match the hostid value on SERVER lines in the license.dat file if the machine is a server) on any machine support by FLEXlm. Its usage is: lmhostid 3.3.5 Using lmremove ==================== This utility generally allows the system administrator to remove a single user's license for a specified feature. However, you cannot use lmremove to remove a COBOL license. If you attempt to do this, lmremove appears to succeed and lmgrd logs a message stating that the license was removed; however, the license is not given up and returned to the pool of available licenses. 3.3.6 Using lmreread ==================== This utility causes the license daemon to reread the license file and start any new vendor daemons that have been added. In addition all pre-existing vendor daemons will be signaled to reread the license file for any changes in feature licensing information. lmreread cannot be used to change server node names or port numbers. Its usage is as follows: lmreread [-c license_file] [daemon] where -c license_file specifies the license file to operate on. In this case, only lmreread will read the license file specified; lmgrd will reread the license file it originally read at start-up time. daemon specifies the vendor daemon to signal. If a vendor daemon is specified in this manner, only the named vendor will reread the license file. In this case, lmgrd will not reread the license file (and will not start any new vendor daemons that might have been added). 3.3.7 Using lmstat ================== This utility allows the system administrator and/or user to quickly monitor the status of all FLEXlm licensing activities. lmstat returns information such as: * which daemons are running * users of individual features * users of features served by a specific vendor daemon Its usage is: lmstat [-a] [-S] [daemon]] [-f [feature]] [-i feature] [-s [server]] \ [-t value] [-c license_file] [-A] where -a displays all information about all features. -A lists all active licenses. -c license_file specifies license file to operate on. -f feature_name lists the users of the specified feature. -i feature_name prints information about the named feature, or all features if no feature name is given. -s server_name displays status of server node(s). -S daemon restricts output to one vendor daemon, and the feature and users of that daemon. -t value sets lmstat time-out value. lmstat -a is a potentially expensive command. If there are numerous active users, lmstat can generate a lot of network activity. It should be used sparingly. 3.3.8 Using lmswitchr ===================== This utility switches the report writer REPORTLOG log file for the specified feature. It will also start a new REPORTLOG file if one does not already exist. Its usage is: lmswitchr [feature] [new-file] where feature is any feature the DAEMON supports. new-file is the new file path. Note that report writer is part of the FLEXadmin End-User Administration Tool available from GLOBEtrotter Software. 3.3.9 Using lmver ================= This utility reports the FLEXlm version of a library or binary file. Its usage is: lmver [filename] where -filename is the name of a program or library. For example, to determine the version of FLEXlm used by COBOL, type: $ lmver $COBDIR/coblib/libcobol.sl You can use the following command to get the FLEXlm version of a binary: $ strings file | grep Copy If you omit the argument, lmver tries to find the FLEXlm library liblmgr.a and warns you that it cannot find it. --------------------------------------------------------------------------- 3.4 FLEXlm Directory Structure ============================== The script hpmfocdsini installs the FLEXlm components in and below the directory flexlm, which is installed by default in /usr/local. If you specified an alternate location to hpmfocdsini, substitute that path for /usr/local in the following lists: /usr/local/flexlm/bin/ lmcksum lmdiag lmdown lmgrd lmhostid lmremove lmreread lmstat lmswitchr lmutil lmver /usr/local/flexlm/licenses/ licenses.dat /usr/local/flexlm/options/ hpcuplangs.opt /usr/local/flexlm/vendors/ HPCUPLANGS --------------------------------------------------------------------------- 3.5 Troubleshooting FLEXlm ========================== This section documents areas of FLEXlm that have given customers difficulty in the past. --------------------------------------------------------------------------- NOTE: If you cannot find the answer to your question here, you can find additional information on configuring and administering FLEXlm GLOBEtrotter's FLEXlm End User Manual, and their FAQ at GLOBEtrotter's web site: http://www.globetrotter.com --------------------------------------------------------------------------- 3.5.1 Troubleshooting Tips ========================== 3.5.1.1 Wrong hostid for Machine ================================ License manager states hostid is wrong for machine. The vendor daemon checks the hostid listed on the SERVER line in the license file; if it does not match the hostid of the machine it is running on, this message will be printed. Possible causes include * you are trying to run the license server on a different machine from the machine the file was made for * the hostid of the machine you are running on changed (for example, the CPU board was replaced or the HP ID module was moved) * the hostid in the license file was modified Verify that the hostid of the machine running the vendor daemon matches the hostid specified in the license file on the SERVER line for the vendor. You can run the lmhostid program to see what FLEXlm thinks the hostid is. You may not modify the hostid in the license file. If the hostid of your server machine changes, you will have to get a new license file from Hewlett-Packard. 3.5.1.2 lmver Cannot Find FLEXlm Library liblmgr.a ================================================== The intended usage of lmver is $ lmver program_or_library_name This tells you what version of FLEXlm is bound in. If you omit the argument, lmver tries to find the FLEXlm library liblmgr.a and warns you that it cannot find it. 3.5.1.3 Who do I call if I need help with FLEXlm? ================================================= If you have questions about FLEXlm, contact Licensing Services at: Hewlett-Packard World Wide Licensing Services California, U.S.A. Phone: 650-960-5111 fax: 650-960-5670 e-mail: hplicense@mayfield.hp.com Hours: Monday through Friday, 8am-5pm PST Grenoble, France Phone: +33.(0)4.76.14.15.29 fax: +33.(0)4.76.14.25.15 e-mail: codeword_europe@hp-france-gen1.om.hp.com Hours: Monday through Friday, 8am-5pm GMT +1 3.5.2 Known Problems ==================== 3.5.2.1 lmdiag Logs "expected and harmless" error -37 Messages ============================================================== lmdiag logs "expected and harmless" error -37 messages to the lmgrd log file. These messages are of the form: HH:MM:SS (HPCUPLANGS) Feature hpmfcobol parameter mismatch checkout denied (current: nnn,request: nnn) HH:MM:SS (HPCUPLANGS) DENIED: "hpmfcobol" user@host (Duplicate selection mismatch for ths feature (-37,55) Ignore these messages. --------------------------------------------------------------------------- 3.6 FLEXlm Error Messages (Return Status Values) ================================================ The following information on FLEXlm error messages (status return values) is from the GLOBEtrotter Software FLEXlm Reference Manual, Appendix D, "Status Return Values." It is reprinted here with permission from GLOBEtrotter Software. These error messages are also located on the HP Micro Focus Object COBOL web site: http://www.hp.com/go/cobol/ --------------------------------------------------------------------------- NOTE: For errors not listed in this section, check the "Frequently Asked Questions" pages on the GLOBEtrotter web site: http://www.globetrotter.com --------------------------------------------------------------------------- ____________________________________________________________________________ The following information on FLEXlm error messages (status return values) is from the GLOBEtrotter Software "FLEXlm Reference Manual" (Appendix D, Status Return Values). It is reprinted here with permission from GLOBEtrotter Software. Please note that the "ACTION" text was added by Hewlett-Packard. (c) Copyright 1996-2000 Globetrotter Software, Inc. All rights reserved. ____________________________________________________________________________ Appendix D - FLEXlm Status Return Values These are all the possible errors returned from lc_xxx() functions. Error number Symbolic Name and Description -1 LM_NOCONFFILE "cannot find license file" The license file cannot be opened. FLEXlm will attempt to open the standard file /usr/local/flexlm/licenses/license.dat,(or C:\FLEXLM\LICENSE.DAT on Windows and Windows NT) or the file specified by the vendor (via lc_set_attr()), or the file specified by the user in LM_LICENSE_FILE. -2 LM_BADFILE "invalid license file syntax" A feature name is > MAX_FEATURE_LEN, A daemon name is > MAX_DAEMON_LEN. A server name is > MAX_SERVER_NAME. A feature specifies no hostid and # of licenses is <= 0. -3 LM_NOSERVER "cannot connect to a license server" The daemon name specified in the license file FEATURE line does not match the vendor daemon name. -4 LM_MAXUSERS "licensed number of users already reached", The licenses number of users has been reached. -5 LM_NOFEATURE "no such feature exists" The feature could not be found in the license file. A call was made to one of the software license working group usage metering functions (um_xxx_record()). -6 LM_NOSERVICE "no TCP "license" service exists" This happens if a SERVER line does not specify a TCP/port number, and the TCP license service does not exist in /etc/services. -7 LM_NOSOCKET "no socket connection to license manager server" lc_disconn() was called after the process had been disconnected from the socket. This error can also occur if an internal error happens within l_sndmsg() or l_rcvmsg(). -8 LM_BADCODE "encryption code in license file is inconsistent" The code in a license file line does not match the other data in the license file. This is usually the result of not building all the software components with the same encryption seeds. Check makekey.c, lsvendor.c, and your application code carefully to insure that they are all built with the same vendor code. ACTION: Run lmcksum on your license file to confirm that it is valid. If you have started lmgrd with the LM_LICENSE_FILE environment variable set, check that LM_LICENSE_FILE is set to the same value for all users of Micro Focus Object COBOL. -9 LM_NOTTHISHOST "invalid host" The hostid specified in the license file does not match the node on which the software is running. -10 LM_LONGGONE "feature has expired" The feature has expired, i.e., today's date is after the expiration date in the license file. -11 LM_BADDATE "invalid date format in license file" The start or expiration date in the license file is invalid. -12 LM_BADCOMM "invalid returned data from license server" The port number returned from lmgrd is invalid. An attempted connection to a vendor daemon did not result in a correct acknowledgment from the daemon. The daemon did not send back a message within the timeout interval. A message from the daemon had an invalid checksum. An lc_userlist() request did not receive the correct data. -13 LM_NO_SERVER_IN_FILE "no SERVER lines in license file" There is no SERVER line in the license file. All non-zero license count features need at least one SERVER line. -14 LM_BADHOST "cannot find SERVER hostname in network database" The gethostbyname() system call failed for the SERVER nodename in the license file. -15 LM_ CANTCONNECT "cannot connect to license server" The connect() system call failed, while attempting to connect to the daemon. The attempt to connect to the vendor daemon on all SERVER nodes was unsuccessful. lc_status() returns LM_CANTCONNECT if the feature had been checked out but the program is in the process of reconnecting. If reconnection fails, the final status return is LM_CANTCONNECT. ACTION: If you have started lmgrd with the LM_LICENSE_FILE environment variable set, check that LM_LICENSE_FILE is set to the same value for all users of Micro Focus Object COBOL. -16 LM_CANTREAD "cannot read data from license server" The process cannot read data from the daemon within the timeout interval. The connection was reset by the daemon (usually because the daemon exited) before the process attempted to read data. -17 LM_CANTWRITE "cannot write data to license server" The process could not write data to the daemon after the connection was established. -18 LM_NOSERVSUPP "license server does not support this feature" The feature has expired (on the server node), or has not yet started, or the version is greater than the highest supported version. ACTION: Run lmcksum on your license file to confirm that it is valid. If you have started lmgrd with the LM_LICENSE_FILE variable set, check that LM_LICENSE_FILE is set to the same value for all users of Micro Focus Object COBOL. If you see this message when you run lmdiag, you can ignore it; This is a known problem in the FLEXlm software and has been reported to GLOBEtrotter. -19 LM_SELECTERR "error in select system call" The select() system call failed. This should never happen in a client program. -20 LM_SERVBUSY "license server busy (no majority)", The license server is busy establishing a quorum of server nodes so that licensing can start. This error is very rare, and checkout should be retried if this occurs. -21 LM_OLDVER "license file does not support this version" The version requested is greater than the highest version supported in the license file FEATURE line. -22 LM_CHECKINBAD "feature checkin failure detected at license server" The checkin request did not receive a proper reply from the vendor daemon (the license might still be considered in use). -23 LM_BUSYNEWSERV "license server temporarily busy (new server connecting)" The vendor daemon is in the process of establishing a quorum condition. New requests from clients are deferred during this period. This request should be retried. -24 LM_USERSQUEUED "users are queued for this feature" This error is similar to MAXUSERS, but supplies the additional information that there are other users in the queue for this feature. -25 LM_SERVLONGGONE "license server does not support this version of this feature" The version specified in the checkout request is greater than the highest version number the daemon supports. -26 LM_TOOMANY "request for more licenses than this feature supports" A checkout request was made for more licenses than are supported in the license file. This request will never succeed. -27 LM_CANTREADKMEM "cannot read /dev/kmem" The file /dev/kmem is not readable on this system. This error will only occur if using extended hostid checking, which is no longer supported in current versions of FLEXlm. -28 LM_CANTREADVMUNIX "cannot read /vmunix" The file /vmunix is not readable on this system. This error will only occur if using extended hostid checking, which is no longer supported in current versions of FLEXlm. -29 LM_CANTFINDETHER "cannot find ethernet device" The ethernet device could not be located on this system. -30 LM_NOREADLIC "cannot read license file" The license file could not be read (errno == EPERM or EACCES). -31 LM_TOOEARLY "feature not yet available" The feature is not enabled yet (current date is before the feature start date). -32 LM_NOSUCHATTR "No such attribute" A call to lc_get_attr() or lc_set_attr() specified an unknown attribute code. -33 LM_BADHANDSHAKE "Bad encryption handshake with daemon" The client performs an encryption handshake operation with the daemon prior to any licensing operations. This handshake operation failed. -34 LM_CLOCKBAD "Clock difference too large between client and server" The date on the client system does not agree closely enough with the date on the server (daemon) system. The amount of difference allowed is set by the software vendor with lc_set_attr(LM_A_MAX_TIMEDIFF, ...). -35 LM_FEATQUEUE "In the queue for this feature" This checkout request has resulted in the process being placed in the queue for this feature. Subsequent calls to lc_status() will yield the status of this queued request. -36 LM_FEATCORRUPT "Feature database corrupted in daemon" The daemon's run-time feature data structures have become corrupted. This is an internal daemon error. -37 LM_BADFEATPARAM "Duplicate selection mismatch for this feature" The checkout request for this feature has specified a duplicates mask that does not match the mask specified by an earlier checkout. This is probably the result of using different versions of your client software, or from having an uninitialized variable in the dup_group field for lc_checkout(). ACTION: This is a known problem in the FLEXlm software and has been reported to GLOBEtrotter. You can ignore these errors. -38 LM_FEATEXCLUDE "User/host on EXCLUDE list for feature" The user/host/display has been excluded from this feature by an end-user's daemon option file. -39 LM_FEATNOTINCLUDE "User/host not on INCLUDE list for feature" The user/host/display has NOT been included in this feature by an end-user's daemon option file. -40 LM_CANTMALLOC "Cannot allocate dynamic memory" The malloc() call failed to return sufficient memory. -41 LM_NEVERCHECKOUT "Feature was never checked out" This code is returned by lc_status() if the feature requested has never been checked out. -42 LM_BADPARAM "Invalid parameter" A call to lc_set_attr() specified an invalid value for its attribute. lc_get_attr(LM_A_MASTER,...) called without connection already established to server. -43 LM_NOKEYDATA "No FLEXlm key data supplied in lc_init() call" No FLEXlm key data was supplied to the lc_init() call. Some FLEXlm functions will be disabled. -44 LM_BADKEYDATA "Invalid FLEXlm key data supplied" Invalid FLEXlm key data was supplied to the lc_init() call. Some FLEXlm functions will be disabled. -45 LM_FUNCNOTAVAIL "FLEXlm function not available in this version" This FLEXlm function is not available. This could be a result of a BADKEYDATA, NOKEYDATA, or DEMOKIT return from lc_init(). -47 LM_NOCLOCKCHECK "Clock setting check not available in daemon" lc_checkout() returns this code when the CLOCK SETTING check between client and daemon is not supported in this daemon. Try calling: lc_set_attr(LM_A_MAX_TIMEDIFF, -1) to disable the clock check. -48 LM_BADPLATFORM "FLEXlm platform not enabled" The software is running on a platform which is not supported by the vendor keys you have purchased. To purchase keys for additional platforms, contact Globetrotter Software, Inc. -49 LM_DATE_TOOBIG "Date too late for binary format" The expiration date format in FLEXlm licenses are good until the year 2027. This is probably a bogus date. -50 LM_EXPIREDKEYS "FLEXlm key data has expired" The FLEXlm Demo vendor keys have expired. Contact Globetrotter Software for new demo keys. -51 LM_NOFLEXLMINIT "FLEXlm not initialized" A FLEXlm function was called before lc_init() was called. Always call lc_init() first. -52 LM_NOSERVRESP "Server did not respond to message" UDP communications failure. UDP communications are not guaranteed. FLEXlm makes a best effort to recover from lost and garbled messages, but this indicates a failure. -53 LM_CHECKOUTFILTERED "Request rejected by vendor-defined filter" lc_checkout() failed because of the vendor defined routine which is set in lsvendor.c: ls_outfilter. -54 LM_NOFEATSET "No FEATURESET line present in license file" lc_ck_feats() called, but no FEATURESET line in license file. -55 LM_BADFEATSET "Incorrect FEATURESET line in license file" Error return from lc_ck_feats() -56 LM_CANTCOMPUTEFEATSET "Cannot compute FEATURESET line" Error return from lc_ck_feats(), which occurs because lc_feat_set() can not compute the FEATURESET line. This can happen because there's no FEATUREs in the file. -57 LM_SOCKETFAIL "socket() call failed" This can occur when the Unix OS runs out of system resources. -58 LM_SETSOCKFAIL "setsockopt() failed" The setsockopt() call has failed. This is likely due to an OS error. -59 LM_BADCHECKSUM "message checksum failure" Communications error -- messages between client and server are encrypted and checksummed for security and integrity. The checksum will usually fail because of poor networking communications. -60 For internal use. -61 LM_SERVNOREADLIC "Cannot read license file from server" This occurs when the license file, via LM_LICENSE_FILE, or lc_set_attr(LM_A_LICENSE_FILE, path), is incorrectly defined. This only occurs when LM_LICENSE_FILE is set to port@host. -62 LM_NONETWORK "Network software (tcp/ip) not available" This is reported on systems where this is detectable. Some systems may have this problem, but the error will not be reported as LM_NONETWORK - system calls will simply fail. -63 LM_NOTLICADMIN "Not a license administrator" Various functions, such as lc_remove() and lc_shutdown(), require that the user be an license administrator, depending on how lmgrd was started. See lmgrd(), lmremove() and lmdown(). -64 LM_REMOVETOOSOON "lmremove request too soon" An lc_remove request occurred, but ls_min_lmremove (defined in lsvendor.c) seconds have not elapsed since the license was checked out. See ls_vendor(). -65 LM_BADVENDORDATA "Bad VENDORCODE struct passed to lc_init()" LM_CODE macro was not used to define the VENDORCODE argument for lc_init. See lm_code.h and lmflex.c for an example of how to use the LM_CODE macro. -66 LM_LIBRARYMISMATCH "FLEXlm include file/library mismatch" An attempt was made to create a licensed binary with mismatching source/header files and liblmgr.a. The source code version must match the linking libraries. -67 For Internal Use -68 For Internal Use -69 For Internal Use -70 For Internal Use -71 LM_BAD_TZ "Invalid TZ environment variable" On some operating systems, the end-user can significantly change the date using the TZ environment variable. This error detects this type of theft. -72 LM_OLDVENDORDATA "'Old-style' vendor keys (3-word)" V3.0 uses 4-vendor keys. This error detects that the LM_CODE macro was used with only 3 keys. -73 LM_LOCALFILTER "Local checkout filter requested request" Request was denied by filter specified in lc_set_attr(LM_A_CHECKOUTFILTER, filter). -74 LM_ENDPATH "Attempt to read beyond the end of LF path" An error occurred with the colon-separated list of license files. -75 LM_VMS_SETIMR_FAILED "SYS$SETIMR call failed" SYS$SETIMR is used on VMS to time out certain FLEXlm system calls. -76 LM_INTERNAL_ERROR "Internal FLEXlm Error - Please report to Globetrotter Software" -77 LM_BAD_VERSION "Bad version number - must be floating point number, with no letters" A line in the license file has an invalid version number. lc_checkout() was called with an invalid version character string. -78 LM_NOADMINAPI "FLEXadmin API functions not available" An attempt to get information from another company's vendor daemon. was made via lc_get_attr(LM_A_VD_*, ...). This function call is only allowed for the client's own vendor daemon. -79 For Internal Use -80 For Internal Use -81 For Internal Use -82 LM_BADPKG "Invalid PACKAGE line in license file" PACKAGE missing or invalid COMPONENTS. A COMPONENT has number of users set, with OPTIONS=SUITE. A COMPONENT has number of users==0 -83 LM_SERVOLDVER `Server FLEXlm version older than client's Vendor daemon FLEXlm version is older than the client's FLExlm version. This is only supported with a v5.0+ client. -84 LM_USER_BASED `Incorrect number of USERS/HOSTS INCLUDED in options file -- see server log' When a feature has the USER_BASED attribute, this error occurs when there no INCLUDE line in the end-user options file for this feature, or the number of users included exceeds the number authorized. See Section 10.1.4, `FEATURE or INCREMENT Line,' on page 92, especially USER_BASED. -85 LM_NOSERVCAP `Server doesn't support this request' This occurs when a vendor daemon with a FLEXlm version older than the client is being used. The daemon didn't understand and respond to the request made by the application. -86 LM_OBJECTUSED `This license object already in use' (Java only). -87 LM_MAXLIMIT `Checkout exceeds MAX specified in options file' End-user option MAX has been specified for this feature. -88 LM_BADSYSDATE `System clock has been set back' Returned from checkout call. -89 LM_PLATNOTLIC `This platform not authorized by license' Returned from checkout call where FEATURE line specifies PLATFORMS="...". ___________________________________________________________________________ ___________________________________________________________________________ Chapter 4: Documentation ___________________________________________________________________________ 4.1 COBOL Information ===================== The documents described in this section are available with HP Micro Focus Object COBOL/UX. To order sets of the printed documentation contact your Hewlett-Packard Sales Representative and request product number B5449EA. However, please note that the printed documentation set was not revised for Micro Focus version 4.1.30; only the online html files were revised. If you order B5449EA, you will receive the printed manual set for Micro Focus version 4.1.10. The HP Micro Focus Object COBOL/UX Programmer's Guide is only available in online format. It was not printed and is not included in the printed documentation kit, B5449EA. --------------------------------------------------------------------------- NOTE: HP Micro Focus Object COBOL/UX Release Notes for Version B.13.40 is NOT included on the HP Instant Information CD. --------------------------------------------------------------------------- 4.1.1 Locating COBOL Information ================================ The table below summarizes where to find your COBOL information: _______________________________________________________________________________ $COBDIR/ docs/html/ $COBDIR/ HP Micro Focus Information library.htm docs Printed COBOL Website(a) ------------------------------------------------------------------------------- HP Micro Focus Object Yes Yes COBOL/UX Programmer's Guide ------------------------------------------------------------------------------- Micro Focus Object COBOL Yes Yes v4.1.30 documentation set ------------------------------------------------------------------------------- Micro Focus Object COBOL Yes(b) Yes v4.1.10 documentation set ------------------------------------------------------------------------------- HP Micro Focus COBOL/UX Yes Yes Yes(c) Yes Release Notes ------------------------------------------------------------------------------- Micro Focus Release Documents Yes ------------------------------------------------------------------------------- GLOBEtrotter FLEXlm End User Yes(d) Guide ------------------------------------------------------------------------------- GLOBEtrotter FLEXlm Error Yes(e) Yes(e) Yes(e,c) Yes Messages ------------------------------------------------------------------------------- a. URL: http://www.hp.com/go/cobol b. Printed documentation set ordered separately, product number B5449EA c. Shipped with COBOL product as Option AVN d. Links to http://globetrotter.com e. Part of the Release Notes _______________________________________________________________________________ 4.1.2 Online html Manuals ========================= Hewlett Packard now includes the Micro Focus documentation set and the Hewlett-Packard HP Micro Focus Object COBOL/UX ProgrammerÕs Guide online in html (hyper-text markup language) format. You can view and print these manuals with any html browser, such as Netscape's Navigator. These files are shipped with the product in a compressed format. After COBOL is installed, you can use the docstool script to uncompress and install the online manuals. This script can also be used to remove these manuals at a later date. For more information on installing the online manuals, see Section 2.3.3 Installing the Online Documentation Files. To view the installed manuals, from your html browser load the following file: $COBDIR/cobol/docs/html/library.htm This page links you to all of the available COBOL online books: * HP's online HP Micro Focus COBOL/UX Programmer's Guide * Micro Focus Object COBOL V4.1.30 online documentation set consisting of: o Getting Started with Object COBOL o Compatibility Guide o Error Messages o Language Reference o Language Reference - Additional Topics o Object COBOL User Guide o Object COBOL Character Tools o OO Programming with Object COBOL o Programmer's Guide to Communications o Programmer's Guide to File Handling o Programmer's Guide to Creating User Interfaces o Programmer's Guide to Writing Programs o Dialog System Character Tools o License Management Facility Administrator's Guide o Master Index and Glossary 4.1.3 Online Files in $COBDIR/docs ================================== Hewlett-Packard includes three online files along with the Micro Focus files in the $COBDIR/docs directory. hp_README This document from Hewlett-Packard contains a report of closed defects for this release. In some releases this file may be empty. hp_relnotes.txt This document is the text file of this HP release document. However, the printed Release Notes may contain the latest release information. For instance, there may be changes in the characters in the banner and the cobwhat output. For the most recent release information, check the printed Release Notes. hp_relnotes.ps This document is the PostScript file of this HP release document. The following online documents from Micro Focus are located in the $COBDIR/docs directory: --------------------------------------------------------------------------- NOTE: The information in these online files apply to HP 9000 computers running HP-UX 10.20 and 11.x. --------------------------------------------------------------------------- --------------------------------------------------------------------------- NOTE: Any Early Release features from Micro Focus are NOT included in the HP Micro Focus COBOL/UX product. --------------------------------------------------------------------------- appserv.1 The files listed in this document constitute the Application server (also known as the Operating System Extensions). To ship any of the listed files, you must obtain a run-time license. changes.1 This document is for use when maintaining applications created using Micro Focus COBOL systems. It describes the differences that may cause problems and ways of overcoming these problems. It includes documentation of obsolete features no longer documented in the manuals but maintained for compatibility. config.1 This document describes the Run-time Configuration facility supplied with Micro Focus OSX to enable you to port files between Micro Focus COBOL systems for UNIX and Micro Focus COBOL systems for DOS, Windows, Windows NT, Windows 95, and OS/2, and to maintain these files after porting. dialog.1 This document contains information from Micro Focus for the character mode product, including documentation updates, fixed defects, known problems, restrictions, and supplementary information. dsannu.1 This document contains information from Micro Focus for the new features available to subscribers Micro Focus Annual Maintenance Agreement. dsdun.1 This document contains the Documentation Update Notes for Character Mode Dialog System. dsfeat.1 This document contains information on features for Character Mode Dialog System which were not documented in the Micro Focus Object COBOL documentation set. features.1 This document summarizes new features and all Early Release features. Early Release features are normally documented in online documents and not in the printed books. fhutil.1 This document describes the File Handler utilities supplied with Micro Focus OSX to enable you to port files between Micro Focus COBOL systems for UNIX and Micro Focus COBOL systems for DOS, Windows, Windows NT, Windows 95, and OS/2 and to maintain these files after porting. readme.1 This document contains the release notes from Micro Focus, describing errors and restrictions found in the software, and gives information that was not available when the books where printed. They cover all components of Micro Focus COBOL and Micro Focus Toolbox. rebuild.1 This document describes the Rebuild facility supplied with the run-time system to enable you to port files between Micro Focus COBOL for DOS, Windows and OS/2 and Micro Focus COBOL for UNIX and to maintain these files after porting. running.1 This document describes the execution facilities supplied with Micro Focus OSX to enable you to port files between Micro Focus COBOL systems for UNIX and Micro Focus COBOL systems for DOS, Windows, Windows NT, Windows 95 and OS/2; and to maintain these files after porting. sup.1 This document is contains supplemental information from Micro Focus. terminfo.1 This document describes the Terminfo facility supplied with Micro Focus OSX to enable you to port files between Micro Focus COBOL systems for UNIX and Micro focus COBOL systems on personal computers. 4.1.4 Online COBOL Man Pages ============================ The following COBOL man pages are included with the product: * cob(1) * anim(1) * cobrun(1) To be able to access the COBOL man pages with the man command, you must first set and export the MANPATH environment variable, even if you leave the product in the default installation location. See Section 5.1 Known Problems for more information. To set and export the MANPATH environment variable, enter the following command: $ export MANPATH=$COBDIR/man:$MANPATH --------------------------------------------------------------------------- 4.2 Other Useful Information ============================ 4.2.1 HP-UX Documentation ========================= * The Linker and Libraries Online User's Guide is available for HP 9000 systems. This book used to be known as Programming on HP-UX. The online manual can be found at the HP Documentation website at the following URL: http://www.docs.hp.com The online help version comes with HP C, HP C++, HP Fortran, HP Pascal, and HP Micro Focus Object COBOL/UX. Online help can be accessed from any X Window display device, or from the charhelp(1) character-mode help browser. Refer to the following documents for more information on the HP-UX operating system. These HP-UX operating system manuals are also available at the HP Documentation web site noted above. * HP-UX Reference * System Administration Tasks * Installing HP-UX 10.01 and Updating HP-UX 10.0 to 10.01 * Release Notes for HP-UX 10.20 * Upgrading from HP-UX 9.x to HP-UX 10.01 * How HP-UX Works: Concepts for the System Administrator * Installing and Administering NFS Services * HP-UX Symbolic Debugger User's Guide * HP/DDE Debugger Reference * HP/DDE Debugger User's Guide * HP/DDE Debugger Technical Addendum * Using the X Window System * Programming with Threads on HP-UX * Managing HP-UX Software with SD-UX 4.2.2 Third Party Documentation =============================== OSF DCE Threads is an advanced topic and general information about threads and programming with threads can be found in the following books: * OSF DCE Application Development Reference, Revision 1.0, Open Software Foundation, Prentice-Hall, 1993, ISBN 0-13-643834-2. * OSF DCE Application Development Guide, Revision 1.0, Open Software Foundation, Prentice-Hall, 1993, ISBN 0-13-643826-1. ___________________________________________________________________________ Chapter 5: Known Problems, Limitations, and Fixes ___________________________________________________________________________ For a list of HP Micro Focus Object COBOL/UX problems and their fixes, see the Technical Knowledge Database on the HP Electronic Support Center website: http://us-support.external.hp.com/ http://europe-support.external.hp.com/ The Technical Knowledge Database is available to customers with support contracts. 1. Once at the website, enter your User ID and Password, then click 2. On the next page, click Technical Knowledge Database. 3. Verify that your Search Options include "HPUX" under System Type and" Service Request" under Document Type. 4. Enter 35326B in theSearch String field, then click Note: 35326B is the support number for COBOL, B3455A is the support number for Toolbox and B3453A is the support number for Dialog System. Below is some information on additional known problems and limitations with this release of HP Micro Focus COBOL/UX. --------------------------------------------------------------------------- 5.1 Known Problems ================== 5.1.1 You Must Set COBDIR, SHLIB_PATH, and MANPATH ================================================== This version of HP Micro Focus Object COBOL/UX contains a defect that requires that you set and export the environment variables COBDIR, SHLIB_PATH, and MANPATH, even if you leave the product in the default installation location (/opt/cobol/cobdir). To set and export these environment variables (for the default COBOL installed location) , enter the following commands: $ export COBDIR=/opt/cobol/cobdir $ export SHLIB_PATH=$COBDIR/coblib $ export MANPATH=$COBDIR/man:$MANPATH --------------------------------------------------------------------------- 5.2 Limitations =============== 5.2.1 HP-UX Large Files are Not Supported ========================================= As of HP-UX 10.20, HP-UX supports files larger than 2 gigabytes. HP-UX large files are not supported with HP Micro Focus Object COBOL/UX; however, the COBOL run-time system generates an error message (194 file size too large) if HP-UX large files are manipulated from COBOL code. If you must manipulate HP-UX large files, use C code. If your application mixes COBOL and C, your operations on HP-UX large files must not attempt to use COBOL I/O statements. Another option is to use Micro Focus Large Files with file striping as documented in in the section "Callable File Handler" in the online Programmer's Guide to File Handling in $COBDIR/docs/html/library.htm. 5.2.2 HP-UX Kernel Threads are Not Supported ============================================ As of HP-UX 10.30, HP-UX supports kernel threads. However, COBOL only supports threads in the following cases: * COBOL, operating in no-threads mode, can operate in a non-threaded environment. * COBOL, operating in no-threads mode, can operate in the main thread of a kernel-threads based process. * COBOL, operating in a single-thread mode, can operate in at most one thread at any time, in a DCE-threads based process. Any other combination is not supported. --------------------------------------------------------------------------- 5.3 Workarounds and Fixes ========================= 5.3.1 +help Troubleshooting for Systems Running HP CDE ====================================================== The +help option to ld(1) and other compiler products may not work on systems running HP CDE. If it does not work, ensure the environment variable DTHELPSEARCHPATH is set. (It may not be set if you rlogin to a system, for example.) If it is not set, use the following command to set it: $ eval $(dtsearchpath) Ensure the LANG environment variable is set, typically LANG=C. As a workaround, you can view the linker online help using the < ? > $ /usr/dt/bin/dthelpview -helpVolume linker or $ /usr/dt/bin/dthelpview -helpVolume /opt/langtools/lib/help/C/linker.hv --------------------------------------------------------------------------- 5.4 Closed Defects ================== The following defects have been recently closed in HP Micro Focus Object COBOL/UX. You can find a detail report for these closed defects in $COBDIR/docs/hp_README. Product: COBOL/HP-UX S800 Product Nuumber: 35326B ________________________________________________________________________ Number: 1653050005 document that SIGQUIT detected from COBOL spawns a subshell Signed off 07/02/98 in release B11.25 ________________________________________________________________________ Number: 1653083782 h2cpy does not translate C structures with float or double Signed off 09/10/97 in release B08.75 ________________________________________________________________________ Number: 1653095901 calling 'stty' from a closedown procedure gives stty error;STDIN closed? Signed off 09/10/97 in release B11.25 ________________________________________________________________________ Number: 4701287045 MFCOBOL/UX B.08.15: NCG error: ustack not empty (5129) on COMPUTE Signed off 10/16/97 in release B10.42 ________________________________________________________________________ Number: 1653119545 B.08.10: array MOVEs from Linkage to Local-Storage field not correct Signed off 10/15/97 in release B11.27 ________________________________________________________________________ Number: 1653174771 MFCOBOL B.10.32: Rounding of COMP-2 to PIC 9(9) is ignored in COMPUTE Signed off 09/10/97 in release B10.45 ________________________________________________________________________ Number: 1653193516 B.10.xx: rts 907 Signal/Thread assertion failed - with hp_nosignals.o Signed off 09/10/97 in release B11.50 ________________________________________________________________________ Number: 1653198226 B.11.26, B.10.41, B.08.76: rts 153 on ADD with last array item Signed off 09/10/97 in release B11.27 ________________________________________________________________________ Number: 1653212548 MFCOBOL B.11.2x: rts 114 on MOVE S9(09) COMP to S9(06) COMP in Linkage Signed off 09/10/97 in release B11.28 ________________________________________________________________________ Number: 1653219550 MFCOBOL B.11.27 generates bad _hp_ver_lhpcobl.c file: libhpcobol.1l Signed off 09/10/97 in release B11.50 ________________________________________________________________________ Number: 1653221788 MFCOBOL B.11.2x CBL_CHECK_FILE_EXIST gives incorrect file size results Signed off 09/10/97 in release B11.28 ________________________________________________________________________ Number: 1653223230 MFCOBOL B.11.2x: adiscf enable/disable fkeys "Invalid option" 5003379099 Signed off 02/11/98 in release B11.30 ________________________________________________________________________ Number: 1653233007 MFCOBOL rts 114 (Signal 11) on MOVE PIC 9(2)V9(1) to PIC 99.9, if -C NLS Signed off 07/02/98 in release B12.26 ________________________________________________________________________ Number: 1653234203 MFCOBOL B.10.41-B.11.28: COMPUTE F1(A) = F1(A) - F2 wrong native result Signed off 07/02/98 in release B12.26 ________________________________________________________________________ Number: 1653238485 MFCOBOL B.10.42-B.12.25 wrong result in ADD or MULTIPLY if native code Signed off 07/02/98 in release B11.30 ________________________________________________________________________ Number: 4701240358 fhrebuild creates an invalid key file larger than the original key file Signed off 09/11/97 in release B08.76 ________________________________________________________________________ Number: 4701252338 rts 114 when MOVE of array element PIC XX to data item PIC XX; gnt or .o Signed off 09/16/97 in release B08.76 ________________________________________________________________________ Number: 4701260901 SETTINGS option shows NOLINKCOUNT"512" if LINKCOUNT=512 is specified Signed off 10/16/97 in release B11.25 ________________________________________________________________________ Number: 4701293498 Cross session animation doesn't work for accept statements Signed off 10/16/97 in release B10.45 ________________________________________________________________________ Number: 4701310409 B.10.xx: rts 115 (Signal 22) with Sybase; signal_regime tunable missing Signed off 10/16/97 in release B10.43 ________________________________________________________________________ Number: 4701325431 -C WRITETHRU (for MF buffer) buffers @ 512 bytes for LS files. Signed off 10/16/97 in release B10.42 ________________________________________________________________________ Number: 4701326314 B.10.xx: rts 114 occurs when EXTERNAL data items accessed, SQLPROT used Signed off 10/16/97 in release B10.42 ________________________________________________________________________ Number: 4701329854 MFCOBOL compiler loops or compiler error 301-S on INITIALIZE w qualifier Signed off 10/16/97 in release B11.27 ________________________________________________________________________ Number: 4701342261 MOVE FUNCTION MAX fails in native code Signed off 10/16/97 in release B11.50 ________________________________________________________________________ Number: 4701343228 Big app w many sorts dies w rtserr 114 in sort module Signed off 10/16/97 in release B11.27 ________________________________________________________________________ Number: 4701344689 IDXFORMAT(4) file is corrupt and can't rebuild Signed off 10/16/97 in release B10.41 ________________________________________________________________________ Number: 4701345165 Target array bounds checking broken. Signed off 10/16/97 in release B11.27 ________________________________________________________________________ Number: 4701347658 Native checker does not always produce an error summary. Signed off 10/16/97 in release B10.41 ________________________________________________________________________ Number: 4701348169 MFCOBOL B.10.41: OPEN INPUT of var len file on WORM drive returns 9/030 Signed off 07/02/98 in release B11.25 ________________________________________________________________________ Number: 4701348524 Variable length temp files required for Variable length sorts Signed off 10/16/97 in release B08.18 ________________________________________________________________________ Number: 4701349258 CCINAMPU hangs on fileshare open on hpux 10.10/10.20 works 10.01 Signed off 07/02/98 in release B11.27 ________________________________________________________________________ Number: 4701349852 animator aborts on pi in B.11.2[67], B.10.4[12] w rts err 114 Signed off 10/16/97 in release B10.43 ________________________________________________________________________ Number: 4701350280 MFCOBOL B.10.40 slow Fileshare performance COMMIT; multiple sync calls Signed off 07/02/98 in release B11.28 ________________________________________________________________________ Number: 4701352252 ncg problem: works as GNT but not as EXE w procedure pointers Signed off 10/16/97 in release B11.28 ________________________________________________________________________ Number: 4701356006 B.11.27: signal 10 on snt caused by LDH instruction on byte-aligned addr Signed off 10/16/97 in release B11.28 ________________________________________________________________________ Number: 4701364877 Colorization doesn't work in v4.1 COBOL for HP Signed off 07/02/98 in release B12.26 ________________________________________________________________________ Number: 4701368209 MFCOBOL B.12.25: rts 115 (Signal 6) cobrun or exe an Object COBOL module Signed off 07/02/98 in release B12.26 ________________________________________________________________________ Number: 4701368233 MFCOBOL B.12.25/B.12.50 V4.1: mkrts for striped files fails with unsats Signed off 07/02/98 in release B12.26 ________________________________________________________________________ Number: 4701371146 COBOL install probably wrong for B.11.25 (hardcoded links to /cobol/bin) Signed off 07/02/98 in release B11.28 ________________________________________________________________________ Number: 4701375394 MFCOBOL B.12.25: fhinfo, fhvalidate, fhconvert fail if filename > 10 ch Signed off 07/02/98 in release B12.26 ________________________________________________________________________ Number: 5003057521 animator Do command does not pass NULL parameters Signed off 10/16/97 in release B12.25 ________________________________________________________________________ Number: 5003147769 copy library file-name is missing from compiler error message 8 Signed off 10/16/97 in release B11.25 ________________________________________________________________________ Number: 5003179275 fhvalidate and fhrebuild fail w/iserrno = 103 on indexed files, lg key Signed off 10/16/97 in release B08.75 ________________________________________________________________________ Number: 5003189118 $set flag(saa) gives extraneous compiler error: 643-OSVS, Source overlap Signed off 10/16/97 in release B08.75 ________________________________________________________________________ Number: 5003198424 copy lib not found, if COBOPT, COBCPY and COPYEXT are set Signed off 10/16/97 in release B08.76 ________________________________________________________________________ Number: 5003225649 Search verb order used to create a key instead of KEY statement in TBL Signed off 10/16/97 in release B08.76 ________________________________________________________________________ Number: 5003230888 anim testme.int | tee -a histlog does not handle input correctly Signed off 07/02/98 in release B12.26 ________________________________________________________________________ Number: 5003233460 compiling with -C XREF gives 'Error in CSI information' in Rpt Writer Signed off 10/16/97 in release B11.25 ________________________________________________________________________ Number: 5003271379 B.08.15: rts 114 on MOVE array item to non-array, ALIGN=4, S9(10) COMP Signed off 10/16/97 in release B11.27 ________________________________________________________________________ Number: 5003286492 B.08.xx: rts 114 when accessing multi-dimensional array in native code Signed off 10/16/97 in release B08.76 ________________________________________________________________________ Number: 5003326124 B.10.40: RTS error 114 unless program compiled with NOCHUNk Signed off 10/16/97 in release B10.42 ________________________________________________________________________ Number: 5003328047 Enhance MFCOBOL to use CCI static port assignment for secure network Signed off 10/16/97 in release B12.25 ________________________________________________________________________ Number: 5003338335 -C IBMCOMP using B.11.40 causes strangeness in compiler Signed off 10/16/97 in release B11.27 ________________________________________________________________________ Number: 5003352724 B.11.25,26: file OPEN fails with file status 35 or 37 if env var Signed off 10/16/97 in release B11.27 ________________________________________________________________________ Number: 5003355834 MFCOBOL B.10.41, B.11.26, B.08.76: COMPUTE w array: wrong result gnt,exe Signed off 10/16/97 in release B10.42 ________________________________________________________________________ Number: 5003356261 Intermittent Fileshare server abort with misc return code Signed off 10/16/97 in release B10.43 ________________________________________________________________________ Number: 5003370692 MFCOBOL: compute tmp-result = tmp-amt * tmp-qty / tmp-qty truncates Signed off 10/16/97 in release B10.43 ________________________________________________________________________ Number: 5003371328 MFCOBOL B.11.25: dsmot fails with PANELS2 Init failure ; error : 00009 Signed off 10/16/97 in release B11.28 ________________________________________________________________________ Number: 5003399246 MFCOBOL NCG: SUBTRACT then ADD gives wrong result - native only Signed off 07/02/98 in release B11.30 ________________________________________________________________________