Micro Focus COBOL Server for UNIX

Welcome to COBOL Server

  • Welcome
  • Product Information
  • Managing Licenses

Featured Sections

  • Tools

Online Resources

  • Micro Focus Infocenter
  • Micro Focus SupportLine
  • Micro Focus Product Updates
  • Micro Focus Knowledge Base
  • Micro Focus Community Forums
  • Micro Focus Training Store

Provide Feedback

  • Contacting Micro Focus
  • Email us feedback regarding this Help


Welcome

COBOL Server provides the execution environment for applications created with Micro Focus Visual COBOL.

COBOL Server and COBOL Server 2012
This product is available in two variants which you can install and use with the same license - COBOL Server which is the deployment environment for COBOL applications created with Visual COBOL for Visual Studio 2010 or Visual COBOL for Eclipse, and COBOL Server 2012 which targets applications created with Visual COBOL for Visual Studio 2012.
Compiling for COBOL Server or for COBOL Server 2012

Visual COBOL for Visual Studio 2010 and Visual COBOL for Visual Studio 2012 each target a different version of the COBOL run-time system - COBOL Server and COBOL Server 2012, respectively.

Ensure that after you've edited the project in the preferred version of Visual Studio, you compile your source code in that version of Visual COBOL which targets the version of the COBOL run-time in which you want your applications to run.

For example, if you build your application using Visual COBOL for Visual Studio 2010 you cannot deploy the target files to COBOL Server 2012; you must use COBOL Server.

  • Product Information
  • Managing Licenses
Parent topic: Micro Focus COBOL Server for UNIX


Product Information

This Product Information covers information available at the time of writing. Up-to-date information is downloadable from the SupportLine Web site.

  • Installing the Product
  • Updates and Product Support
  • Micro Focus End User License Agreement
  • Third Party Software
  • Known Errors and Restrictions
  • Contacting Micro Focus
Parent topic: Welcome


Installing the Product

  • Installing on UNIX
Parent topic: Product Information


Installing on UNIX

  • System Requirements for COBOL Server for UNIX
  • Installing COBOL Server for UNIX
Parent topic: Installing the Product


System Requirements for COBOL Server for UNIX

  • Hardware Requirements
  • Operating Systems Supported
  • Software Requirements
Parent topic: Installing on UNIX


Hardware Requirements

The disk space requirements are:

  • Between 26MB and 54MB for the Sentinel RMS license server depending on the platform.
  • Between 146MB and 350MB for COBOL Server.
    Note: The installation requires extra disk space that equals the size of the product you install.
Parent topic: System Requirements for COBOL Server for UNIX


Operating Systems Supported

  • AIX POWER 6.1/7.1 - 32/64-bit
  • x86-64 running Red Hat Linux 5.5/5.7/6.1 - 32/64-bit
  • Oracle Linux 6 Update 2 with Unbreakable Enterprise Kernel Release 2
  • SPARC running Solaris 10 - 32/64-bit
  • x86-64 running SuSE SLES 11/11 SP1 - 32/64-bit
  • HP IA 11.31 - 32/64-bit

COBOL for JVM is supported on the following platforms:

  • HP IA 11.31 - 32/64-bit
  • x86-64 running Red Hat Linux 5.6/6.1 - 32/64-bit
  • SPARC running Solaris 10 - 32/64-bit
  • x86-64 running SuSE SLES 11/11 SP1 - 32/64-bit
Parent topic: System Requirements for COBOL Server for UNIX


Software Requirements

Before installing this product, you must have the following software installed on your computer:

  • Before installing on Red Hat 6.1, you must have the 32-bit operating system libraries installed:
    • GNU Standard C++ Library - libstdc++(i686 version)
    • The object files for development using standard C libraries – glibc-devel (i686 version)

    Check the Red Hat Web site for more information.

  • To use the Web installer on Red Hat Enterprise Linux 6.1, you must have the following bug fix updates for Red Hat installed:
    • glibc-2.12-1.25.el6_1.3.i686.rpm
    • openldap-2.4.23-15.el6.i686.rpm
    • nss-pam-ldapd-0.7.5-7.el6.i686.rpm
    • zlib-1.2.3-25.el6.i686.rpm
    • nss-3.12.9-9.el6.i686.rpm
    • nss-util-3.12.9-1.el6.i686.rpm
    • cyrus-sasl-lib-2.1.23-8.el6.i686.rpm

    You do not need these updates if you use the full product setup file to install the product.

  1. Java Platform Standard Edition (Java SE) 6 Update 27 or Java 7 is required to execute COBOL JVM code and for native COBOL and Java interoperability.
    Note: On AIX 6.1 v2, the minimum required version is Java 6.0 SR10.

    You can download Java SE from www.oracle.com and install it anywhere on your machine.

Important: This release requires version 10000.2.990 or later of the Micro Focus licensing software. For local servers, you do not need to install it separately, as the setup file installs a new Visual COBOL client and a new licensing server on the same machine.

If you have a network server, you must update the license server before installing the product as the client is not able to communicate with license servers of versions older than 10000.2.660. To check the version of the license server on UNIX, run /var/microfocuslicensing/bin/mfcesver or /var/microfocuslicensing/bin/cesadmintool.sh.

You can download the new version of the license server software from the Micro Focus SupportLine Web site: http://supportline.microfocus.com/websync/SLM.aspx.

Before you start the installation, you need to set the environment as follows:

  • Set the LANG environment variable to pick up localized messages. The LANG settings are English and Japanese only.
  • The Java Development Kit (JDK) is required for compiling Java. The JDK is downloadable from www.oracle.com. After installing the JDK, you must put the tools.jar file for the JDK on your classpath, using a command similar to:
     set classpath=jdk-install-directory\lib\tools.jar
Parent topic: System Requirements for COBOL Server for UNIX


Installing COBOL Server for UNIX

  • Downloading the Product
  • Installing
  • After Installing
  • Installing as an Upgrade
  • Installing Silently
    You can install Micro Focus products silently by using command line parameters to specify the installation directory, user information, and which features to install.
  • UNIX Installer Issues
  • Repairing
  • Uninstalling
Parent topic: Installing on UNIX


Downloading the Product

  1. Use the download links in your Electronic Product Delivery email.

    For more information follow the links for the install instructions and the End User License Agreement.

Parent topic: Installing COBOL Server for UNIX


Installing

To use the Web Installer:

  1. Give the Web installer file execute permissions once it downloaded:
    chmod +x webinstaller_visualcobol_server_2.1_platform
  2. Run the installer with superuser permissions:
    ./webinstaller_visualcobol_server_2.1_platform

    If you don't run this as superuser, you will be prompted to enter the superuser password during the install.

Alternatively, you can use the setup file and install the product as follows:

  1. Give execute permissions to the setup file:
    chmod +x setup_visualcobol_server_2.1_platform
  2. Run the installer with superuser permissions:
    ./setup_visualcobol_server_2.1_platform

    If you don't run this as superuser, you are prompted to enter the superuser password during the install.

    If you set COBDIR to an already installed product, the installer will back up the existing installation and will install this release in the location COBDIR points to. If COBDIR is not set, the installer does a fresh install.

    The COBOL environment is installed by default into /opt/microfocus/VisualCOBOL.

    To install in a different location use the -installlocation="Location" parameter to specify an alternative directory location. For example:

    ./webinstaller_visualcobol_server_2.1_platform -installlocation="full path of new location"

    or

    ./setup_visualcobol_server_2.1_platform -installlocation="full path of new location"

    You can see details about which additional parameters can be passed to the install script if you enter the -help option.

Note:
  • The installation of this product could affect the SafeNet Sentinel licensed components running on your machine. During installation licensing is shutdown to allow files to be updated. To ensure the processes running on your machine are not affected, you need to use the –skipsafenet option, which skips the installation of SafeNet:
    ./setup_visualcobol_server_2.1_platform -skipsafenet
  • To protect the SafeNet Sentinel installation from accidental updating you can create an empty file named SKIP_SAFENET_INSTALL in /var/microfocuslicensing/ as follows:
    touch /var/microfocuslicensing/SKIP_SAFENET_INSTALL

    While the file is present, the SafeNet installer does not make changes to the installation or shutdown the running license daemons. If later licensing needs to be updated, remove the file and install Sentinel RMS server manually.

Parent topic: Installing COBOL Server for UNIX


After Installing

When you have installed the product, you need to set the environment as described below.

  1. To set up your product, execute:
    /opt/microfocus/VisualCOBOL/bin/cobsetenv
  2. To verify that your product is installed, execute:
    cob -Version
Important: These commands set the environment only for the current shell. You need to execute them for each new shell that you start.

To avoid having to run cobsetenv for every shell, add these commands to the shell initialization files (etc/profile, etc/bashrc, etc.)

Parent topic: Installing COBOL Server for UNIX


Installing as an Upgrade

This release works concurrently with version R4 of Visual COBOL, so you do not need to uninstall it. There are two options for installing the latest version in this case:

  • Move the R4 installation to a different location and install the latest version to the default install location, /opt/microfocus/VisualCOBOL.

    This ensures you do not need to change your environment. To move the existing older installation to a different location:

    1. Execute the following command:
      [ as root ] mv /opt/microfocus/VisualCOBOL /opt/microfocus/VisualCOBOLR4
    2. Install the latest version as described in the section Installing.
  • Install the latest version in a different location and set the environment to point to it. To do this, run the Visual COBOL 2.1 installer with the –installlocation option:
    1. Execute the following command:
      ./InstallFile -installlocation="/opt/microfocus/VisualCOBOL2.1"
    2. Execute cobsetenv to set the environment and point to the new install location:
      . /opt/microfocus/VisualCOBOL2.1/bin/cobsetenv
Parent topic: Installing COBOL Server for UNIX


Installing Silently

You can install Micro Focus products silently by using command line parameters to specify the installation directory, user information, and which features to install.

You can use the following command line arguments to install silently on UNIX:

–silent -IacceptEULA

For example, execute:

webinstaller_filename –silent -IacceptEULA

or

setup_filename –silent -IacceptEULA
Parent topic: Installing COBOL Server for UNIX


UNIX Installer Issues

License Infrastructure Installer

On some Solaris platforms, you can receive the following error message when SafeNet license server needs to be installed or upgraded on your machine:

tar: /safenet.tar: No such file or directory

To resolve this issue, wait for the installation to complete and then perform the following:

  1. Navigate to the safenet directory in the COBDIR location.
  2. With superuser permissions execute: ./MFLicenseServerInstall.sh

License Server

On UNIX, you need to configure the computer hostname to ensure the license server will start properly.

To avoid performance issues, "localhost" and the computer hostname must not both be mapped to IP address 127.0.0.1. You should only map "localhost" to IP address 127.0.0.1.

The following is an example of how to specify these entries correctly in the etc/hosts file:

127.0.0.1 localhost.localdomain localhost
IP machinelonghostname machineshorthostname

where IP is the unique IP address of the computer in xx.xx.xx.xx format.

Parent topic: Installing COBOL Server for UNIX


Repairing

If a file in the installation of the product becomes corrupt, or is missing, we recommend to reinstall the product.

Parent topic: Installing COBOL Server for UNIX


Uninstalling

To uninstall this product:

  1. Execute as root the Uninstall_VisualCOBOL2.1.sh script in the $COBDIR/bin directory.
Note: The installer creates separate installations for the product and for Micro Focus License Manager. Uninstalling the product does not automatically uninstall the Micro Focus Licensing Manager or the prerequisite software. To completely remove the product you must uninstall the Micro Focus Licensing Manager as well.

To uninstall Micro Focus License Manager:

  1. Execute as root the UnInstallMFLicenseServer.sh script in the /var/microfocuslicensing/bin directory.

    The script does not remove some of the files as they contain certain system settings or licenses.

You can optionally remove the prerequisite software. For instructions, check the documentation of the respective software vendor.

Parent topic: Installing COBOL Server for UNIX


Updates and Product Support

When you have installed, you need to apply the latest updates if there are any. These are located on the Micro Focus Web site.

Before you can access the Product Updates page, you need to register (first-time users only) and log in with Product Support. To register:

  1. Click Register on the Product Support page.
  2. Enter your details. You will need your product serial numbers, which you can find in the subject line and body of your Electronic Product Delivery Notice email that you received from Micro Focus.

To log in:

  1. Enter your User Name and Password on the Product Support page.

    We recommend you check Auto Login so you don't have to do this every time.

  2. Click Login.

The Product Updates page is now displayed, where you can find the latest update for your product and version number.

You will then be notified on a weekly basis, when you run this COBOL development system, if an update is available. The notification will include a link to the Product Support page from where you can access the update, as described above.

Product Support is a web-based support and information service from Micro Focus. It provides all the latest information and software updates for this COBOL development system:

  • Technical support information
  • Latest product information
  • Documentation updates
  • New and updated demonstrations and templates
  • Hints and tips
  • Lots more - try it and see!
Parent topic: Product Information


Micro Focus End User License Agreement

IMPORTANT: LICENSOR IS PROVIDING THIS SOFTWARE FOR YOUR USE SUBJECT TO YOUR AGREEMENT TO BE BOUND BY THE TERMS AND CONDITIONS SET FORTH BELOW. IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT BY CLICKING ON SETUP'S ACCEPT BUTTON, YOU WILL NOT BE ABLE TO USE THE SOFTWARE. BY CLICKING SETUP’S ACCEPT BUTTON YOU ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT, UNDERSTOOD IT, AND AGREE TO BE BOUND BY ITS TERMS AND CONDITIONS.

WHEREAS, Licensor desires to grant to Licensee, and Licensee desires to accept from Licensor, a license to use Licensed Software (as defined herein) upon the terms and conditions hereinafter set forth; NOW, THEREFORE, Licensor and Licensee agree as follows:

For this End User License Agreement (“License Agreement”) the following terms shall have the meanings given below:

“Blades” means multiple server modules housed in a single chassis each with its own CPU, hard disk and memory.

“Core” means a single unit of processing within a computer chip, comprising an arithmetic logic unit, registers, instruction fetcher and data fetcher/storer. “CPU” (Central Processor Unit) means a data processing unit, normally identified with a single microchip mounted on a single circuit board and can comprise several Cores. A computer “box” can contain several CPUs. The “box” is sometimes referred to as a “server” or a “machine” (or possibly a “mainframe”).

“Licensor” means the Micro Focus named legal entity authorized to license the Licensed Software in the country in which Licensee acquires the Licensed Software.

“Licensed Software” means the object code version of the Licensor computer programs, their accompanying user documentation (“Documentation”) and other supplemental materials as provided to Licensee by Licensor, including but not limited to any software security keys, modifications or additions relating thereto. The Licensed Software shall also include any new releases, updates, revisions, modifications, additions, corrections and fixes of the Licensed Software that Licensee receives under Sections 6 and 7 below or under maintenance for which Licensee has separately contracted and paid. From commencement of this License Agreement, the “Licensed Software” shall also include, and this License Agreement shall apply to, any prior versions of the Licensed Software licensed by Licensee. This License Agreement does not grant Licensee the right to any new releases, updates, revisions, modifications, additions, corrections and fixes of the Licensed Software unless provided by Licensor under Section 6 below. Licensed Software products are available to operate on the Windows, Linux, Unix or other computer platforms and a separate license is required for a Licensed Software product for each computer platform.

“Product Order” means a document that has been (i) executed by Licensee, describing each Licensed Software license purchased and (ii) accepted by Licensor or its authorized distributors. Licensor will accept the Product Order by either confirming Licensor’s acceptance in writing or by delivering the Licensed Software Licensee, whichever occurs first. Each Product Order shall constitute a separate agreement and shall incorporate therein all of the terms and conditions of this License Agreement. In the event of any conflict between the terms of this License Agreement and the terms of any Product Order which have been expressly accepted by a duly authorized signatory of Licensor in writing, such terms of the Product Order shall govern. In no event shall any terms and conditions of Licensee contained in a purchase order or similar document issued by Licensee in connection with this License Agreement or a Product Order apply and any such document issued shall be only for the administrative purposes of identifying the Licensed Software ordered, the number of licenses, and the price to be paid and shall have no other legal effect.

“Disaster Recovery System” is defined as a computer system that is used (i) if a disaster arises and the original production system is unavailable, (ii) for the purposes of disaster recovery testing and/or (iii) for system diagnostics or maintenance of the Disaster Recovery System itself. A Disaster Recovery System does not include any system that is in the same computer cluster as the machine on which the development or production copy of the Licensed Software is installed.

“Virtual Machine” means a software implementation that executes programs like a physical machine where the software running inside the virtual machine is limited to the resources and abstractions provided by the virtual machine.

  1. GRANT OF LICENSE. For payment of the applicable non-refundable license fees identified on the Product Order, Licensor grants solely to Licensee, as an end user, a personal, perpetual, non-transferable, non-sublicensable and non exclusive license to use the Licensed Software subject to the terms and conditions set forth in this License Agreement. Licensee shall have the right to use the Licensed Software solely for its own internal use and benefit. For the avoidance of doubt, the license granted herein does not permit (i) third party contractors (including without limitation outsourcers) to access or use the Licensed Software for Licensee’s internal use and benefit without the prior written consent of Licensor and the payment of an additional license fee, (ii) the public to access or use the Licensed Software (including without limitation, via the internet) except as specifically provided in Annex 1 hereunder, and/or (iii) installation, use or access of the Licensed Software on, in, or from a Virtual Machine except as specifically provided in Annex 1 or Annex 2 hereunder. Where permitted by Licensor pursuant to sections 1(i) and (ii) hereof, Licensee shall be liable to Licensor in respect of any breach of this License Agreement resulting from any access or use by third party contractors and/or the public. Access and/or use of data, results and/or output obtained and/or generated, either directly or indirectly, through the use of any Licensed Software are deemed to be access and/or use of such Licensed Software and such data, results and/or output shall be subject to the licensing terms and restrictions applicable to such Licensed Software. Different license options are available from Licensor as set forth or referred to in Annex 1 (“License Option(s)”), although not all License Options are available for each specific Licensed Software product. The applicable License Option to be purchased by Licensee for the Licensed Software shall be identified in the Product Order. Additional License Options (as appropriate) are required to be purchased by Licensee for use of the Licensed Software on a Disaster Recovery System or for load-balancing, fail-over, training, or testing purposes. Licensed Software purchased for testing purposes will be subject to the Test License Option terms and restrictions set forth in Annex 1.E. Certain Licensed Software may also be subject to additional terms and conditions as set forth in the “Specific Software Terms” located in Annex 2. The Specific Software Terms will prevail in the event of any conflict.
  2. USER RESTRICTION. Licensee agrees not to:
    1. Copy and distribute the Licensed Software, in whole or in part, for internal use without paying Licensor the applicable additional fees, except (i) for making a reasonable number of archival back-up copies; or (ii) as expressly authorized by Licensor in writing; or (iii) for making a reasonable number of copies of the Documentation supplied to Licensee by Licensor in electronic form. Licensee shall reproduce and affix all copyright and other proprietary rights notices appearing in or on the Licensed Software, including the notices of all third party suppliers and all those included in any Third Party Software, as defined below in all such copies thereof.
    2. Copy and/or distribute the Licensed Software, in whole or in part, to third parties without first entering into a separate distribution license agreement with Licensor or permit use or access to all or part of the Licensed Software to any third party except as specifically provided in Annex 1 hereunder. For the avoidance of doubt, third party(ies) include without limitation contractors, outsourcers, Licensee’s customers and the public.
    3. Transfer, ship or use the Licensed Software outside the continent in which it was originally licensed to Licensee, except as otherwise specified in Annex 1 and/or Annex 2.
    4. Install, access or use the Licensed Software on an operating system other than the operating system for which the Licensed Software was originally licensed to Licensee, except as otherwise specified in Annex 1 and/or Annex 2.
    5. Assign, sell, rent, lease, lend, sublicense, outsource or otherwise transfer the Licensed Software to any third party, or authorize or appoint any third party to do so.
    6. Use the Licensed Software for timesharing, facilities management, outsourcing, hosting, service bureau use, other data processing services to third parties or like purposes.
    7. Modify the Licensed Software or provide any person with the means to do the same.
    8. Create derivative works, translate, disassemble, recompile or reverse engineer any Licensed Software or attempt to do so (except to the extent applicable law specifically permits such activity).
    9. Alter, destroy, or otherwise remove any proprietary notices or labels on or embedded within the Licensed Software or Documentation.
    10. Utilize for itself, or permit any third party to utilize, any software application program created, in whole or in part, utilizing any Licensed Software without a valid and properly granted Deployment Product License.
    11. Use the Licensed Software in a manner other than as specifically permitted in this License Agreement.
  3. AUDITS. Licensee agrees to (i) keep records of and provide the location, model and serial number of any and all machines on which the Licensed Software is installed or from which the Licensed Software is accessed, and the names of and how many users are accessing the Licensed Software, (ii) implement a reasonable mechanism or process to ensure that Licensee’s use of the Licensed Software does not exceed the number of licenses granted, (iii) take all necessary steps to destroy or erase all Licensed Software codes, programs and other proprietary information before disposing of any media containing the Licensed Software, and (iv) promptly provide written notice to Licensor if Licensee’s usage exceeds the license granted. Upon Licensor’s reasonable request, but not more frequently than annually without reasonable cause, Licensee shall furnish Licensor with a statement signed by a director and/or auditor, as required by Licensor, verifying the above and shall permit Licensor to audit the use of the Licensed Software at such times as may be mutually agreed upon. In the event Licensee’s usage exceeds the license granted, without prejudice to any other rights or remedies Licensor may have, including without limitation injunctive relief, Licensee agrees to pay Licensor the then current license and maintenance fees for the use of the additional licenses. Further, if such usage exceeds the license granted by more than five percent (5%), Licensee shall also reimburse Licensor for the reasonable cost of such audit in addition to other amounts due.
  4. DOCUMENTATION. One (1) electronic copy of Licensor’s standard Documentation, describing Licensor’s recommended use and application of the Licensed Software, will be furnished free of additional charge to Licensee by Licensor with the Licensed Software. Printed copies of any documentation may be available for purchase from Licensor or its authorized distributors.
  5. TERM OF LICENSE. This License Agreement and Licensee’s license for the Licensed Software is perpetual, unless a subscription/term license has been purchased by Licensee, and is subject to earlier termination as provided in this Section 5. Licensor may terminate this License Agreement and Licensee’s license to the Licensed Software immediately by giving Licensee written notice of termination in the event that either (i) Licensee breaches any term or condition of this License Agreement and Licensee has failed to remedy such breach within ten (10) days of the date of notice from Licensor to Licensee or (ii) Licensee is wound up, has a receiver appointed or enters into liquidation or bankruptcy or analogous process or processes in Licensee’s home country. Termination shall be without prejudice to any other rights or remedies Licensor may have. Licensee may at any time terminate this License Agreement voluntarily by giving written notice of termination to Licensor. In the event of any termination Licensee will have no right to keep or use the Licensed Software or any copy of the Licensed Software for any purpose and Licensee shall destroy and erase all copies of such Licensed Software in its possession or control, and forward written certification to Licensor that all such copies of Licensed Software have been destroyed or erased.
  6. MAINTENANCE. Where Licensee purchases maintenance services, Licensee’s initial maintenance term will begin upon delivery to Licensee of the Licensed Software and continue for one (1) year thereafter unless otherwise specified in the applicable annual maintenance agreement or in the Product Order, or earlier if the license is terminated. Where Licensee purchases maintenance for any Licensed Software product licensed hereunder, Licensee hereby agrees that it shall purchase such support services for all of Licensee’s licensed copies of such Licensed Software product on the relevant computer platform. Maintenance services provided by Licensor will be subject to Licensor’s then current applicable annual maintenance agreement unless otherwise agreed by the parties in writing.
  7. LIMITED WARRANTY. Licensor warrants for a period of ninety (90) days from delivery to Licensee (“Warranty Period”) (i) that the media on which the Licensed Software is supplied is free from defects in materials or workmanship under normal use and (ii) that the copy of the Licensed Software delivered to Licensee conforms in all material respects to the Documentation. As the sole and exclusive remedy for not meeting part (i) of the above warranty, Licensor’s sole obligation shall be to repair or replace free of charge any defective media on which the Licensed Software is delivered if the media is returned to Licensor by Licensee during the Warranty Period. As the sole and exclusive remedy for not meeting part (ii) of the above warranty, Licensor shall repair or replace the Licensed Software free of charge or if Licensor reasonably determines that such remedy is not economically or technically feasible, Licensee shall be entitled to a full refund of the license fee and any maintenance fee paid by Licensee with respect to that particular Licensed Software and Licensee’s license to use such Licensed Software will terminate. The warranty set forth in this Section 7 shall not apply if the defect in the Licensed Software is the result of: (a) the Licensed Software not being used in accordance with the Documentation, this License Agreement or with the platform(s) for which the Licensed Software has been designed and licensed by Licensor; or (b) the Licensed Software having been altered, modified or converted by Licensee or any third party except as may be specified in the Documentation; or (c) the malfunctioning of Licensee’s equipment; or (d) accident or abuse; or (e) service by any unauthorized person; or (f) other software used by Licensee which has not been provided by Licensor or for which the Licensed Software is not designed and licensed for operation; or (g) Third Party Software, as defined below; or (h) any other cause occurring after initial delivery of the media to Licensee unless caused directly by Licensor. The foregoing states the complete and entire remedies that Licensee has under this warranty. Licensor shall have no responsibility for any warranty claims made outside of the Warranty Period.
  8. DISCLAIMER OF WARRANTY. The Licensed Software cannot be tested in every possible operating environment, therefore Licensor does not warrant that the functions contained in the Licensed Software will meet Licensee’s requirements, that operation of the Licensed Software will be uninterrupted, or that the Licensed Software is error free. EXCEPT AS SET FORTH HEREIN AND TO THE EXTENT PERMITTED BY LAW, ALL OTHER WARRANTIES, EXPRESSED OR IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, QUALITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXCLUDED ON THE PART OF LICENSOR AND ITS THIRD-PARTY SUPPLIERS. Licensee acknowledges that Licensee is responsible for the selection of the Licensed Software to achieve Licensee’s intended results and for the installation of, use of and results obtained from the Licensed Software.
  9. LIMITATION OF LIABILITY. ANY LIABILITY OF LICENSOR SHALL BE LIMITED IN THE AGGREGATE TO THE AMOUNTS PAID BY LICENSEE FOR THE LICENSED SOFTWARE. THIS LIMITATION APPLIES TO ALL CAUSES OF ACTION, INCLUDING WITHOUT LIMITATION BREACH OF CONTRACT, BREACH OF WARRANTY, NEGLIGENCE, STRICT LIABILITY, MISREPRESENTATION AND OTHER TORTS. THE LIMITATIONS OF LIABILITY DESCRIBED IN THIS SECTION 9 ALSO APPLY TO LICENSOR’S THIRD-PARTY SUPPLIERS. LICENSOR’S AND ITS THIRD-PARTY SUPPLIERS’ LIMITATIONS OF LIABILITY ARE NOT CUMULATIVE. Licensee’s remedies in this License Agreement are Licensee’s exclusive remedies.

    NEITHER LICENSOR NOR ANY OF ITS THIRD-PARTY SUPPLIERS SHALL BE LIABLE FOR ANY INJURY, LOSS OR DAMAGE, WHETHER INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL NOR FOR ANY LOST PROFITS, CONTRACTS, LOSS OF DATA OR PROGRAMS, OR THE COST OF RECOVERING SUCH DATA OR PROGRAMS, EVEN IF INFORMED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE.

    NEITHER THIS LICENSE AGREEMENT NOR ANYTHING IN THIS SECTION 9 SHALL PURPORT TO EXCLUDE OR RESTRICT THE LIABILITY OF LICENSOR OR ITS THIRD-PARTY SUPPLIERS TO ANY EXTENT NOT PERMITTED BY LAW.

  10. HIGH-RISK USES. The Licensed Software is not fault tolerant, nor designed, manufactured or intended for use in hazardous environments requiring fail-safe performance (including, without limitation, the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems) in which failure of the Licensed Software could lead directly or indirectly to death, personal injury or severe physical or environmental damage. Licensor and its suppliers specifically disclaim any express or implied warranty of fitness for a particular purpose and shall have no liability for any use of the Licensed Software in any high-risk situations.
  11. OWNERSHIP. Licensor (or its affiliates) and where applicable Licensor’s third party suppliers have and will retain all ownership rights to the Licensed Software, together with any complete or partial copies thereof. Such ownership rights include without limitation all patent rights, copyrights, trademarks, trade secrets, service marks, related goodwill, and confidential and proprietary information relating thereto. This License Agreement does not convey any proprietary interest to Licensee with respect to the Licensed Software other than the license specified herein. Where the Licensed Software provided under this License Agreement contains or is derived from portions of materials provided by a third-party supplier under license to Licensor, Licensor has assumed responsibility for the selection of such materials and their use in producing the Licensed Software and any such third-party suppliers are intended beneficiaries of this License Agreement.
  12. NOTICE TO U.S. GOVERNMENT END USERS. The Licensed Software is provided to the United States Government with RESTRICTED RIGHTS and its supporting documentation is provided with LIMITED RIGHTS. Use, duplication, or disclosure by the United States Government is subject to the restrictions as set forth in FAR52.227-14 and DFAR252.227-7013 et seq. or the successor as appropriate. Manufacturer is Micro Focus (US), Inc., 9420 Key West Drive, Rockville, MD 20850 as or on behalf of Licensor.
  13. LICENSE FEES, PAYMENT, AND TERMS. Licensee agrees to pay the applicable end user license fees for the Licensed Software within thirty (30) days of the date of invoice or such earlier date as is specified in the Product Order. End user license fees are non-refundable except as provided in Section 7 above, or in the Specific Software Terms below, and shall be paid without deduction, including without limitation, of any withholding tax. End user license fees are exclusive of any applicable transportation charges, value added and other applicable taxes and duties and all such amounts shall be paid or reimbursed by Licensee. Late payments shall accrue interest at the rate of 1.5% per month compounded or, if lower, the maximum rate allowed by law.
  14. RELATED SERVICES. Licensee shall be responsible for obtaining and installing all proper hardware and support software (including operating systems) and for proper installation and implementation of and training concerning the Licensed Software. In the event that Licensee retains Licensor to perform any services with respect to the Licensed Software (for example: installation, implementation, maintenance, consulting and/or training services), Licensee and Licensor agree that such services shall be subject to Licensor’s then current standard terms, conditions and rates for such services unless otherwise agreed in writing by Licensor.
  15. THIRD PARTY SOFTWARE AND COMPONENTS. The Licensed Software may contain certain named third party software programs that Licensee shall license directly from the third party subject to such third party’s terms and conditions (for example Adobe Acrobat or Microsoft Internet Explorer) (“Third Party Software”). All Third Party Software is provided by the licensor of the Third Party Software and solely under such third party’s terms and conditions and not by Licensor. Therefore the obligations, duties and rights of Licensor and Licensee under this License Agreement do not apply to such Third Party Software. Additionally, Licensor has embedded certain run time or other elements provided by third party suppliers to Licensor (“Third Party Components”). Such Third Party Components may also be loaded on the Licensed Software media. Third Party Components are licensed to Licensee pursuant to this License Agreement. Licensee may only access Third Party Components of the Licensed Software in the course of using the Licensed Software. Licensee may not make or attempt any direct access to any such Third Party Components other than with the Licensed Software. The Third-Party Software is the property of its respective third party supplier to Licensor. Such third party suppliers own all copies of the Third-Party Software, however made. Licensee agrees not to contest the ownership of the Third Party Components nor use any trademark or service mark belonging to such third party suppliers. All limitations, restrictions and obligations applicable to the Licensed Software set forth in this License Agreement shall apply to Licensee’s use of the Third Party Components. Licensee agrees that such third party suppliers are intended third party beneficiaries of all terms and conditions of this License Agreement intended to protect intellectual property rights in the Licensed Software (including the Third Party Components) and limit certain uses thereof.
  16. PRIVACY. The Licensed Software may contain features which may allow Licensee to collect data from, control and/or monitor computers running the Licensed Software deployed by Licensee without notice to or knowledge by users of the Licensed Software. Licensee is solely responsible for, and assumes all liability with respect to, the collection of data with respect to its users of the Licensed Software including, without limitation, notifying such users and complying with all data collection, privacy and other regulations, laws, industry standards and rights of others applicable to any such activity. Licensee shall indemnify and hold Licensor harmless from and against any damages, claims, losses, settlements, attorneys' fees, legal fees and court costs and other expenses related to any such activities or any claims in connection therewith. To the extent permitted by law, by entering into this License Agreement, Licensee hereby expressly consents to (i) Licensor sending information to Licensee from time to time advertising the various products that Licensor provides, whether or not such products are provided under this License Agreement; (ii) the use of Licensee’s name in Licensor customer lists, promotional materials and/or press releases; and (iii) the collection and use by Licensor of information about the computer system on which the Licensed Software is installed (e.g. product version, serial number) for internal security and licensing purposes; Licensor does not use this information to identify individuals utilizing such software.
  17. MISCELLANEOUS. Licensor may assign this License Agreement to any member of Licensor’s group of companies or to a purchaser of the intellectual property rights in the Licensed Software, but otherwise neither this License Agreement nor any rights hereunder may be assigned (any change of control merger, sale or other transfer of all, or substantially all, of the assets of Licensee shall be included in the meaning of an assignment) nor duties delegated by either party, and any attempt to do so will be void. If Licensee acquires the Licensed Software in North America, the laws of the state of Maryland govern this License Agreement and it shall be subject to the exclusive jurisdiction of the courts of the State of Maryland. If Licensee acquires the Licensed Software in France, Germany or Japan, this License Agreement is governed by the laws of the country in which Licensee acquired the Licensed Software. In the rest of the world the laws of England govern this License Agreement. The aforesaid applicable law shall apply without regard to conflicts of laws provisions thereof, and without regard to the United Nations Convention on the International Sale of Goods. Other than for North American transactions, this License Agreement shall be subject to the exclusive jurisdiction of the courts of the country determining the applicable law as aforesaid. This License Agreement is in addition expressly made subject to any United States, United Kingdom or European Union laws, regulations and other restrictions regarding export or re-export of computer software and technology. Licensee agrees not to export or re-export any Licensed Software or derivative thereof in contradiction to any such applicable restriction. Except for the Product Order, this License Agreement is the complete and exclusive statement of agreement between the parties relating to the license for the Licensed Software and supersedes all proposals, communications, purchase orders, and prior agreements, verbal or written, including without limitation prior end user license agreements in relation to the Licensed Software between the parties and end user license agreements embedded in such Licensed Software. Upon Licensee’s properly authorized installation of any update and/or upgrade of any Licensed Software licensed hereunder, the license granted to such prior version and/or release shall terminate after a ninety (90) day transition period from such installation and only the license to such updated and/or upgraded Licensed Software shall continue. No employee, agent, or representative of Licensor has the authority to bind Licensor to any oral representation or warranty concerning the Licensed Software. No representation or statement not expressly contained in this License Agreement nor any supplement, modification, or amendment of this License Agreement will be binding on either party unless executed in writing by a duly authorized representative of each party to this License Agreement.

ANNEX 1

A. LICENSE OPTIONS FOR THE FOLLOWING SOFTWARE PRODUCTS:

All Micro Focus Application Development and Application Deployment products, including Net Express®, Net Express® with .NET, Net Express® for Eclipse, Server Express™, Server Express™ for Eclipse, Micro Focus Studio™ Enterprise Edition, Micro Focus Studio™ for COBOL Developers, Micro Focus Studio™ for ISVs, SOA Express, Micro Focus Server™ Enterprise Edition, Micro Focus Server ™ for COBOL, Micro Focus Server™ for .NET, Micro Focus Server ™ for SOA, Extend®, Relativity®, RM/COBOL®, Open PL/I, Open PL/I SQL, Open PL/I Run Time, ReUzeDeveloper, ReUze Server, XDBC, Database Connectors and Xcentrisity® including portions thereof, other products within the same product families and other Software Products where indicated by Licensor.

  1. Development License Options
    1. Named User License. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on either (i) a single machine which may be accessed by the named end users for those licenses or (ii) on a single host machine or server (“Host Server”) which may be accessed by any of the named end users licensed. A Named User License means that only one named person can use each license and that named person has the right to unlimited access to the Licensed Software. A Named User License is not based on concurrent users, but instead on an actual named user basis. Licensor reserves the right at any time to require Licensee to provide a list of the named end users. Licensee may change a named end user provided that the change is made either permanently away from the named end user or temporarily to accommodate the use of the Licensed Software by a temporary worker while the named end user is absent, but in no event more than once every 30 days.
    2. Lines of Code License. Licensed Software provided under the Lines of Code license option requires, as a condition of use, that Licensee use a usage counter containing a credit for the number of lines of code that Licensee has purchased (“Usage Counter”). Licensee shall have sole responsibility for installing, configuring, and administering the Usage Counter. The Usage Counter will allow Licensee to create metering control files in order to track the number of lines of code which Licensee has purchased and which Licensee accesses. Licensee hereby acknowledges and agrees that unless Licensee can demonstrate to Licensor’s satisfaction that the Usage Counter was faulty on delivery to Licensee, Licensee is solely responsible for any lost, damaged, corrupted, destroyed, inaccurate or improperly used metering control files or metering transaction files, and in any such circumstance, may be required to pay an additional license fee on a line of code basis for lines of code which may have been already accessed and recorded using the Usage Counter. Each line of code which Licensee has accessed using the Licensed Software and which has been properly recorded using the Usage Counter may be re-accessed without the need to pay an additional license fee. However, if Licensee creates an additional line of code by updating a line of code source member which has already been accessed and metered by the Licensed Software, then Licensee will need to pay an additional license fee to access such additional line of code using the Licensed Software. Upon exhaustion of prepaid license fees, however, Licensee must purchase more lines of code in order to continue to use the Licensed Software on lines of code not yet accessed by the Licensed Software and properly recorded using the Usage Counter. Any prepaid license fees are non-cancellable and non-refundable.
  2. Deployment License Options
    1. User License for Authorized Users. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on unlimited Host Servers for use by the total number of named individuals for whom Licensee has paid the applicable license fee. The Licensed Software may not be used or accessed by (a) individuals who are not named individuals; or (b) any other software or hardware device that does not require a named individual to use or access it. A named individual means an individual identified by Licensee by name who is authorized to use any device or other software program that may access the Licensed Software, either directly or indirectly through any other software program, regardless of how such access occurs or if such individual uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. The Licensed Software may not be used or accessed by any other software or hardware device that does not require an individual to use or access it including, without limitation, batch processing (as defined in subsection (b)(ii) below). Licensor reserves the right at any time to require Licensee to provide a list of the named individual(s). Licensee may change a named individual provided that the change is made either permanently away from the named individual or temporarily to accommodate the use of the Licensed Software by a temporary worker while the named individual is absent, but in no event more than once every 30 days.
    2. Server License. There are two options for server-based licenses.
      1. Server License for Concurrent Users. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on the designated Host Server specified in the Product Order for use by the maximum number of Concurrent Users for whom Licensee has paid the applicable license fee. Concurrent Users are individuals who are actively using any device or other software program that may access the Licensed Software either directly, or indirectly through any other software program, regardless of how such access occurs or if such user uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. The Licensed Software may not be used or accessed by any other software or hardware device that does not require an individual to use or access it including, without limitation, batch processing (as defined in subsection (b)(ii) below). Licensee may change the designated Host Server to an equivalent Host Server for which Licensee has paid the applicable license fee. Licensee may only use the Licensed Software on or access the Licensed Software from one Host Server at any one time. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee’ customers to access and use the Licensed Software via the internet and/or Licensee’ terminals in connection with Licensee’ internal business purposes (for example to access internet banking from Licensee) but not for the public’ and/or Licensee’ customers’ own internal use.
      2. Server License for CPUs. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on the designated Host Server specified in the Product Order and have the Licensed Software executed by up to the total number of Cores and other processing devices within such Host Server. The Host Server comprises the entire computer system (i.e. combined hardware) that will be running the Licensed Software (e.g. all CPUs, Cores, Blades and other processing devices running an operating system compatible with that which the Licensed Software is designed for and which are contained in, and/or can be accessed by, the same computer system, even if one or more of such CPUs, Cores, Blades or other processing devices are not accessing or running the Licensed Software). Each Core or other processing device on a multi-core or multi-processing device requires its own CPU license. For example a dual core single CPU Host Server will require a 2 CPU license (in the absence of any Blades or other processing devices). The Licensed Software is for use by an unlimited number of Licensee’s internal users, other software devices and hardware devices. A Server License for CPU is the only license authorized for use or access by Licensee for any batch processing. Batch processing is defined as the execution of one or more task, transaction or program by a computer system without the interaction of the end user with the Licensed Software while such tasks, transactions or programs are being executed by the system. Batch processing includes situations where a queue of jobs is processed as resources become available and is in contrast to transaction or interactive processing. Licensor reserves the right at any time to require Licensee to provide a specification of the Host Server. Licensee may change the designated Host Server provided that the total number of CPU and Core licenses required in the new Host Server does not exceed the total number of CPU and Core licenses designated in the Product Order. Licensee may only use or access the Licensed Software from one Host Server at any one time. Licensee is required to purchase a license for each Host Server that accesses or uses the Licensed Software either directly or indirectly through any other software program, regardless of how such access occurs, or if the Host Server, CPU or operator uses any hardware or software that reduces the apparent number of CPU, Cores, blades or other processing devices that are using the Licensed Software, such as by using a terminal service. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee’ customers to access and use the Licensed Software via the internet and/or Licensee’ terminals in connection with Licensee’ internal business purposes (for example to access internet banking from Licensee) but not for the public’ and/or Licensee’ customers’ own internal use.
  3. reUZE Mainframe Migration Licensing. Micro Focus reUZE software products may be licensed for installation and use solely with computer environments which meet the following criteria, provided Licensee complies with the restrictions set forth in this Subsection 3 in addition to those contained in the License Agreement. The licensing model in this Subsection 3 is only applicable to the reUZE software products and is not available for licensees who exceed one or more of the following limitations: (i) Mainframe Size Limitation: The Micro Focus reUZE software is expressly limited for use where Licensee’s entire mainframe estate (the “Licensee Mainframe System”) does not exceed a collective performance speed of 50 MIPS (million instructions per second). The Licensee Mainframe System shall include all mainframe systems owned, leased and/or operated (either by Licensee or a third party) by, or for the benefit of, Licensee (including but not limited to the system environment which the applicable application is being migrated from). The collective performance speed benchmark test shall be a collective measurement of the total possible performance of all such mainframe system(s). In the event that the Licensee Mainframe System exceeds a collective performance speed greater than 50 MIPS, Licensee shall not be permitted to utilize the reUZE software product and must contact Licensor for proper licensing of its computer system(s); (ii) CPU and Core Requirements: Notwithstanding Subsection 2(b)(ii) of this Annex 1A, a Deployment Product License option for a Server license for CPU shall be limited by the number of CPUs instead of the combination of Cores, Blades, CPUs and other processing devices; and (iii) Application Limitation: The reUZE software is expressly limited for use by Licensee solely with a specific application(s). Such application(s) shall be designated in writing in the Product Order.

B. LICENSE OPTIONS FOR THE FOLLOWING SOFTWARE PRODUCTS:

OnWeb™, RUMBA™, ViewNow™, Modernization Workbench™, Analyzer Express™, Analyzer Architect ™, Business Rule Manager ™, Enterprise View Express ™, Data Express™, Mainframe Express Enterprise Edition Data Express™, Modernisation Workbench Data Express®, OPTIMAL TRACE®, QACENTER®, QADIRECTOR®, QALOAD®, QARUN®, RECONCILE®, TESTPARTNER®, TRACKRECORD®, CARS®, TEST FACTORY™, DEVPARTNER® including portions thereof, other products within the same product families and other Software Products where indicated by Licensor.

  1. Workstation License Licensed Software provided under this License Option gives Licensee the right to install and use one copy of the Licensed Software on one stand-alone workstation. Licensee may not (i) install the Licensed Software on any networked workstation (e.g., a server) that allows more than one user to use a copy of the Licensed Software, or (ii) use the Licensed Software other than on one stand-alone workstation at a time. Licensee may transfer the Licensed Software to another stand-alone workstation and reactivate it for use on such other stand-alone workstation provided that the Licensed Software is removed and all copies of it are deleted from the stand-alone workstation from which it is transferred. Such transfers may not be undertaken more often than once every 30 days.
  2. Named User License Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on either (i) a single machine which may be accessed by the named end users for those licenses or (ii) on one or more host machines or servers which may be accessed by any of the named end users licensed. A Named User License means that only one named person can use each license and that named person has the right to unlimited access to the Licensed Software. A Named User License is not based on concurrent users, but instead on an actual named user basis. Licensor reserves the right at any time to require Licensee to provide a list of the named end users. Licensee may change a named end user provided that the change is made either permanently away from the named end user or temporarily to accommodate the use of the Licensed Software by a temporary worker while the named end user is absent, but in no event more than once every 30 days.
  3. Volume of Data Licensed Software provided under this option gives Licensee the right to utilize the Licensed Software with the volume of data (the number of terabytes) identified in the Product Order for each of the applicable modules or extensions licensed with the Licensed Software. Volume of data is measured as the original volume of Licensee’ production data to be processed utilizing the Licensed Software before any data reduction process by the Licensed Software or otherwise has been applied. The same data source (defined as a database table or a file) and data may be processed multiple times without counting it more than once towards the total volume of data processed by the Licensed Software, however any additional data and/or data sources (that is, new or increased amounts to the original data source) are counted cumulatively towards such total volume of data number.
  4. Concurrent User License Licensed Software provided under this License Option gives Licensee the right to install and use one copy of the Licensed Software on the designated Host Server (as defined above) specified in the Product Order for use by the maximum number of Concurrent Users (defined above) for whom Licensee has paid the applicable license fee. Licensee may connect any number of workstations to the Host Server; however, the total number of users who may access and use the Licensed Software at any given time is limited by the number of Concurrent Users expressly authorized by Licensor in the Product Order. The total number of Concurrent Users is one (1), unless Licensor expressly authorized Licensee to connect more than one Concurrent User.
  5. Concurrent Users with Load Sharing Configuration Licensed Software provided under this License Option gives Licensee the right to install and use one copy of the Licensed Software on each server supported by a single load sharing device. Licensee may connect any number of workstations to the load sharing device and its connected servers; however, the total number of users who may access and use the Licensed Software at any given time is limited by the number of Concurrent Users expressly authorized by Licensor in the Product Order. The total number of Concurrent Users is one (1), unless Licensor expressly authorized Licensee to connect more than one Concurrent User.
  6. Server Based Thin Client License Licensed Software provided under this License Option gives Licensee the right to install and use one copy of the server portion of the Licensed Software on one server. If installation of the server portion of the Licensed Software requires a thin client component to be installed, Licensee may install and use one copy of the thin client portion of the Licensed Software on one workstation per each thin client license that is specified in the Product Order and for which Licensee has paid the applicable license fee.
  7. Processor Capacity License Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on up to the total number of Cores and other processing devices within each CPU on the designated Host Server specified in the Product Order. Licensee may install an unlimited number of copies of the Licensed Software on single-user computers to allow communication with the designated single Host Server. Licensee may not reinstall or operate the Licensed Software on multiple host processors without Licensor’s prior written consent and payment of all applicable fees.

C. LICENSE OPTIONS FOR THE FOLLOWING SOFTWARE PRODUCTS:

CaliberRM™, TeamDefine™, Together®, StarTeam®, Tempo™, TeamDemand®, TeamFocus™, TeamAnalytics®, TeamInspector™, SilkCentral®, Test Manager™, SilkTest®, Silk4J™, SilkPerformer® including portions thereof, other products within the same product families and other Software Products where indicated by Licensor.

Regardless of the type of license, each copy of the Licensed Software contains (i) software that provides services on a computer called a server (“Server Software”) and (ii) software that allows a computer or workstation to access or utilize the services provided by the Server Software (“Client Software”). For any type of license acquired, Licensee may install one copy of the Server Software on a single computer (the computer running the Server Software shall be referred to as the “Server”). The number of Client Software copies that may be installed is determined by the type of license acquired as set forth below.

  1. Named User A Named User license means Licensee may allow only one (1) designated person in Licensee’s organization (“Named User”) to use the Licensed Software per Named User license purchased (each, a “Named User License”). The foregoing Named User Licenses shall be for access and use, only by the equivalent number of Named Users licenses purchased. For each Named User, Licensee may install the Client Software on up to five (5) computers provided that the Named User is the only individual permitted to use the Licensed Software.
  2. Concurrent User A Concurrent User License means Licensee may install the Client Software on a reasonable number of computers or machines, provided that the Licensed Software is used only by as many concurrent users at any given moment in time as Licensee has purchased concurrent licenses and provided further that Licensee’s use of the Licensed Software (both Client Software and Server Software) is only on computers or machines located in the Territory and accessed only by users physically located in the Territory. The foregoing license shall be for access and use, only by the equivalent number of concurrent users for whom Licensee has paid the applicable license fees. As used in this Section, use or in use means that the Licensed Software is "in use" on a computer or machine when it is loaded into random access memory (RAM) of that computer and “access” means the ability to use, copy or operate the Licensed Software . The Licensed Software may not be shared or used concurrently on computers or machines located outside of the Territory or in such a way to enable use or access by users located outside the Territory. ‘Territory’ means the geographical area in which the Licensed Software may be used. The use in the Territory shall be subject to applicable export restrictions. Territory may be any one, and only one, of the following three geographic areas: Americas Territory, EMEA Territory or AsiaPac Territory each as defined below. The Territory shall be based on the primary business location of the Licensor, unless otherwise specified in a Product Order. The geographic Territories are: (i) ‘Americas Territory’ including and limited to those geographical areas found within the boundaries of North and South America. (ii) ‘Europe, Middle East and Africa Territory’ or ‘EMEA Territory’ including and limited to those geographical areas found within the boundaries of Europe, Middle East and Africa, including all the countries which are part of the European Union, Switzerland, Norway, Jersey, Guernsey, Isle of Man, Iceland, Monaco, Andorra, Liechtenstein, San Marino, Albania, all the countries of the former Yugoslavia, Israel, Turkey, countries of the Arab Middle East, all the countries of the former Soviet Union, Africa, Madagascar, and the Islands of the South Indian Ocean. (iii) ‘Asia Pacific Territory’ or ‘AsiaPac Territory’ including and limited to those geographical areas found within the boundaries of Asia and Australia/Pacific including South Korea, Japan, China, Taiwan, Hong Kong, and Macau India, Maldives, Pakistan, Myanmar, Nepal, Bhutan, Bangladesh, Thailand, Laos, Cambodia, Vietnam, Singapore, Malaysia, Indonesia, East Timor, the Philippines, Brunei, Papua New Guinea, the Pacific Ocean Islands, Australia, and New Zealand.
  3. Virtual User (SilkPerformer only) A "Virtual User" represents a simulation of a particular individual user executing a transaction or sequence of operations. Virtual Users are further qualified by class, and may be licensed on either a Node-Locked or Concurrent User basis. If a Virtual User is licensed on a Node-Locked basis (as provided below) (“Node-Locked Virtual User License”), that Virtual User may be associated with a Multi-Machine Controller (“MMC”) component of the Licensed Software only on the particular system for which the Virtual User is licensed. If a Virtual User is licensed on a Concurrent User basis (as provided below) (“Concurrent Virtual User License”), then that Virtual User may be associated with any licensed instantiation of a MMC at any one time, but during the operation of that instantiation, may not be associated with any other instantiation of a MMC at the same time. By way of example; if 50 Virtual Users are licensed on a Concurrent User basis, Licensee may simultaneously associate all 50 with one MMC instantiation; or simultaneously may associate 20 with one MMC instantiation and 30 with a second MMC instantiation; but could not, for example, simultaneously associate 30 with each of the two MMC instantiations. A "Web Virtual User" is a Virtual User limited to performing actions in basic web-based applications making use of the common web protocols set forth in the accompanying release notes. A "Standard Virtual User" is a Virtual User that has all of the rights of a Web Virtual User, and that may additionally make use of certain client-server, database and other protocols as set forth in the accompanying release notes. A "Premium Virtual User" is a Virtual User that has all of the rights of a Standard Virtual User, and that may additionally make use of certain protocols for packaged third-party applications and complex enterprise technologies as set forth in the accompanying release notes. Node-Locked Virtual User Licenses and Concurrent Virtual User Licenses are available for the MMC or Service Analysis Module (“SAM”) component of the Licensed Software. A Node Locked Virtual User License means Licensee may use the Licensed Software in object code form on a production basis on one (1) computer and to permit the Licensed Software to be used and accessed at any one time by no more than the number of users indicated in the applicable Product Order (each a "Node Locked User"). If no number is indicated, the number shall be 1. A Concurrent Virtual User License means the same as the Concurrent User license option above.

Notes (i) Multiplexing software: The use of one or more external tools, including multiplexors or replicators, to reduce the number of users directly connected to the Licensed Software shall not exempt Licensee from acquiring licenses for all users. For example, use of multiplexing or connection pooling software or hardware to reduce the number of users directly connected to the Licensed Software, the number of Named Users or Concurrent Users within Licensee’s organization using the Licensed Software shall be measured as the number of distinct inputs to the multiplexing or connection pooling front end and Licensee shall purchase the equivalent number of Named User or Concurrent User Licenses. If Licensee uses replicator software, Licensee may not use the Licensed Software or share licenses in any way not explicitly provided for in this License Agreement. (ii) APIs: Any user of any third party application that calls any Licensed Software application programming interfaces (“Product APIs”) must have a valid license to connect to the Licensed Software. Licensee shall not, and shall not allow others, to reverse engineer, decompile, or disassemble the Product APIs. Commercial distribution of any products that include Product APIs requires a separate distribution license and such license is not granted by this License Agreement. (iii) TeamInspector: TeamInspector is licensed on a Named User basis only. (iv) Connectors: A license purchased for this Licensed Software allows use of such software in any quantity solely in conjunction with TeamAnalytics that is licensed and ordered separately.

D. LICENSE OPTIONS FOR THE FOLLOWING SOFTWARE PRODUCTS:

All Application Middleware products including AppServer™ and VisiBroker® including portions thereof, other products within the same product families and other Software Products where indicated by Licensor.

  1. Development License Options
    1. Named User: For each Named User License, Licensee may install and execute the Licensed Software on one (1) computer for use by one (1) person in Licensee’s organization solely to develop, compile (including byte code compile), and test, in source or object code form, Licensee’s own application programs and other works ("Works") designed to work with the Licensed Software. Unless Licensee has purchased a valid Deployment License as described below, Licensee may not deploy or use the Licensed Software on a production basis. The Licensed Software contains certain time-out features designed to prevent the Licensed Software from being deployed in a runtime environment for longer than a specified period without Deployment License keys. Deployment License keys will be provided to Licensee at such time as Licensee purchases the requisite Deployment Licenses. WORKS CREATED USING THE LICENSED SOFTWARE MAY REQUIRE THE LICENSED SOFTWARE IN ORDER TO RUN. WITHOUT THE REQUISITE DEPLOYMENT LICENSE KEYS, THE LICENSED SOFTWARE WILL BE DISABLED AND THOSE WORKS MAY NO LONGER RUN. LICENSEE SHOULD THEREFORE TAKE PRECAUTIONS TO AVOID ANY LOSS OF DATA THAT MIGHT RESULT.
  2. Deployment License Options
    1. Concurrent User: For each Concurrent User Deployment License, License may install the Licensed Software, in executable form only, on a server accessed and used by multiple users over a network, provided that the Licensed Software is used only by as many concurrent users at any given moment in time as Licensee has purchased concurrent licenses and provided further that use of the Licensed Software is only in the Territory and accessed only by users physically located in the Territory. The foregoing license shall be for access and use, only by the equivalent number of concurrent users for whom Licensee has paid the applicable license fees, solely to create, compile (including byte code compile), test and deploy, in source or object code form, Works. As used in this Section, use or in use means that the Licensed Software is "in use" on a computer or machine when it is loaded into random access memory (RAM) of that computer. The Licensed Software may not be shared or used concurrently on computers or machines located outside of the Territory or in such a way to enable use or access by users located outside the Territory.
    2. Server/CPU: For each Server/CPU Deployment License Licensee may install and execute the Licensed Software in object code form on a production basis on one (1) server hardware unit that is operating the platform designated in the applicable Product Order and that has no more than the number of CPUs designated in the applicable Product Order and to permit the Licensed Software as so installed to be accessed at any one time by an unlimited number of concurrent users. Licensee may not install or execute the Licensed Software on any type of device that has a greater number of CPUs and Licensee may not, under a given Server/CPU Deployment License, install or execute the Licensed Software on more than one (1) computer. Licensee may use and deploy the Licensed Software either as a Server or as a Client. Use of the Licensed Software as a "Server" means to manage and control the automated exchanges of information with one or more remote computers through various telecommunications channels. Use of the Licensed Software as a "Client" means to operate the Licensed Software on a computer to facilitate communications with the Server. The Client shall not act as or perform the functions of a Server. A Client may make only a maximum of 10 concurrent call backs. A Client shall not have POA (Portable Object Adapter) policies with the following values: LifespanPolicyValue.PERSISTENT; RequestProcessingPolicyValue.USE_SERVANT_MANAGER; RequestProcessingPolicyValue.USE_DEFAULT_SERVANT Subject to these restrictions and limitations and any additional restrictions or limitations that may appear in the applicable Product Order, Licensee may install the Client on an unlimited number of computers. Licensee receives no right to deploy Clients without the purchase of a Server/CPU Deployment License.
    3. Backup Server License Option for AppServer and VisiBroker Licensee may install the Licensed Software on a single backup server and use the Licensed Software in object code form solely for backup or disaster recovery purposes (“Backup Server License”). Licensee may not use the Licensed Software on a production basis except during periods when one or more copies of the Licensed Software for which Licensee has purchased a Deployment License are nonfunctional, and, in such event, only in accordance with the terms of the Deployment License.
    4. Standby Server License Option for AppServer and VisiBroker Licensee may install the Licensed Software on a single standby server and use the Licensed Software in object code form solely in a standby, non-production mode for use in the event the primary server fails (“Standby Server License”). Licensee may not use the Licensed Software on a production basis under a Standby Server License except during periods when one or more copies of the Licensed Software for which Licensee has purchased a Deployment License are nonfunctional, and, in such event, only in accordance with the terms of the Deployment License.

E. OTHER LICENSE OPTIONS

  1. System Partitioning /LPAR/IFL Licensed Software may be licensed for installation and use on computer systems which incorporate logical partitioning (LPAR), and/or Integrated Facility for Linux (“IFL”) provided such rights have been expressly granted to Licensee by Licensor in writing and Licensee complies with the restrictions set forth in this Section. The licensing models in this Section 1 are only applicable to Server type licenses and are not available for computer systems where system resources (e.g. Cores/CPUs) may be scaled down or varied (e.g. “Pay Per Use” or “Pay Per Forecast” models).
    1. Logical Partitioning (LPAR): The licensing requirements of computer systems (e.g. a Host Server) which incorporate hard and/or soft partitioning shall have their licensing requirements determined as follows:
      1. Hard Partitioning: Hard partitioning is established by using a hard physical partition to physically segment a single larger server so that the Host Server utilizing the Licensed Software is a separate and distinct smaller system (that is, each separate system acts as a physically independent, self-contained server with its own CPUs, operating system, separate boot area, memory, input/output subsystem and network resources). Examples of such hard partitioning include: Dynamic System Domains (DSD) -- enabled by Dynamic Reconfiguration (DR), Solaris 10 Containers (capped Containers only), LPAR (adds DLPAR with AIX 5.2), Micro-Partitions (capped partitions only), vPar, nPar, Integrity Virtual Machine (capped partitions only), Secure Resource Partitions (capped partitions only), and Static Hard Partitioning. For computer systems where hard partitioning has been employed to create the Host Server being utilized to operate the Licensed Software, such Host Server shall be licensed pursuant to the terms and conditions set forth in this Section 1 as if such Host Server where a separate and distinct computer system. For example, where the total computer system has 8 Cores/CPUs but only 4 Cores/CPUs have been hard portioned to use the Licensed Software, Licensee shall only be required to license such 4 Cores/CPUs on such hard partitioned system.
      2. Soft Partitioning: Soft partitioning is established by using the computer systems operating system resource manager to segment and limit the number of Cores/CPUs where the Licensed Software is running by creating areas where processor resources are allocated and limited within the same operating system. Examples of such soft partitioning include: Solaris 9 Resource Containers, AIX Workload Manager, HP Process Resource Manager, Affinity Management, Oracle VM, and VMware. For computer systems where soft partitioning has been employed to create the Host Server being utilized to operate the Licensed Software, such Host Server shall be licensed pursuant to the terms and conditions set forth in this Section 1 as if such Host Server where a separate and distinct computer system but the Cores/CPU required to be licensed shall be an “expected” Cores/CPU number calculated as the ratio of the number of Cores/CPUs soft partitioned as a percentage of the entire computer system’ Cores/CPUs, increased by ten percent (10%). For example, on an 8 Core/CPU computer system where soft partitioning has been utilized such that only 4 Cores/CPUs are allocated to use the Licensed Software, a Server License fee charge equal to 60% of the total computer system Cores/CPUs would be required (50%+10% = 60% of an 8 Core/CPU system license fee).
    2. Integrated Facility for Linux (“IFL”): An Integrated Facility for Linux or IFL Host Server is established by using a dedicated Host Server where the IFL Host Server is isolated from general use and is only capable of utilizing the Linux operating system and running Linux applications and cannot run other operating systems or applications. For IFL Host Server computer systems being utilized to operate the Licensed Software, such IFL Host Server shall be licensed pursuant to the terms and conditions set forth in this Section 1 as if such IFL Host Server were a separate and distinct computer system. For example, where the total computer system that has 8 Cores/CPUs but the IFL Host Server is a 4 Cores/CPUs IFL computer system and the IFL system is the only system using the Licensed Software, Licensee shall only be required to license such 4 Cores/CPUs on such IFL Host Server system.
    3. LPAR and IFL Host Server Verification: Licensee shall provide to Licensor, upon commencement of this License Agreement and at such other times as Licensor may reasonably request, confirmation that Licensee’s computer systems comply with the LPAR and/or IFL license requirements set forth in Subsections 1(a) and (b) above. Such confirmation shall be signed by a director or officer of Licensee and shall be accompanied by all information as Licensor reasonably requires to verify that Licensee is utilizing the Licensed Software in compliance with the terms and conditions of the License Agreement. The foregoing is in addition to Licensor’s rights under Section 3 of the License Agreement.
  2. Evaluation License Option Licensed Software provided under this License Option gives Licensee a term license to use the Licensed Software within Licensee’s organization during the evaluation term specified in writing by Licensor, solely for evaluation and testing purposes on a single computer system and not for development, commercial, or production purposes. Licensee may not reproduce or distribute the Licensed Software. Licensee’s results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor’s prior written consent. At any time during the evaluation term or upon completion thereof, Licensee may, upon written notification to Licensor and payment of the applicable license fee, replace the evaluation license with a license to use the Licensed Software pursuant to one of the other applicable options listed in Annex1. In the absence of such notification by Licensee, the evaluation license shall automatically terminate at the end of the evaluation term and Licensee shall return, or, if Licensor so directs, delete and destroy all such Licensed Software and provide Licensor with written confirmation of such deletion and destruction being completed. Licensor may, in its sole discretion, grant Licensee an extension to the evaluation term subject to receiving a written request and reasons for such request from Licensee prior to expiration of the evaluation term. Licensor will specify any such agreed extension in writing to Licensee. Licensed Software provided by Licensor free of license fee charge shall be deemed to be provided pursuant to this Evaluation License Option unless otherwise agreed in writing. In the absence of any contrary period specified in writing by Licensor, the evaluation term shall be deemed to be thirty (30) days. In relation to Licensed Software provided pursuant to this Evaluation License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement.
  3. Test License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely for Licensee’ internal testing purposes on a single computer system. At no time may Licensee use the Licensed Software for development, commercial, or production purposes, nor may Licensee reproduce or distribute the Licensed Software or any software application programs created with it. The applicable license fee for this License Option will be determined by the access or use to be tested. For example, batch process testing will require the payment of the applicable license fee for a Licensor server license for CPU. Licensee’ results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor’s prior written consent. If Licensee uses the Test Licenses for any purpose other than for Licensee’ internal testing purposes, the Test License shall terminate automatically and without notice. Upon such termination, Licensee may convert the terminated Test License to a standard license type listed above by paying the applicable conversion fee. In relation to Licensed Software provided pursuant to this Test License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement.

ANNEX 2 SPECIFIC SOFTWARE TERMS

The following terms and conditions apply to the applicable Licensed Software products named below and supersede any conflicting terms and conditions set forth elsewhere in this License Agreement:

ALL VERSIONS OF NET EXPRESS®, SERVER EXPRESS™, MICRO FOCUS STUDIO™, MICRO FOCUS SERVER™, EXTEND®, RELATIVITY®, RM/COBOL® , REUZE DEVELOPER, OPEN PL/I AND XCENTRISITY®. For this Licensed Software Licensee has the option to use the Licensed Software licenses purchased either (i) for internal development purposes, or (ii) to reproduce and distribute internally, as both options are described in Annex 1, any software application program created by Licensee using any such Licensed Software product, in whole or in part, as a part of Licensee’ own application software product (“Licensee Application Software”). Where the foregoing option (ii) is selected it is contingent upon Licensee (a) including Licensor’s copyright notice for the Licensed Software on the product label and as a part of the sign-on message for such Licensee Application Software product; and (b) indemnifying, holding harmless and defending Licensor and its third-party suppliers from and against any claims or lawsuits, including attorneys’ fees, legal fees and court costs that arise out of, or result from, the use or distribution of such Licensee Application Software. Licensee can only reproduce and distribute Licensee Application Software to third parties after entering into a separate distribution agreement with Licensor. Usage and distribution of the Licensed Software arises both by the explicit distribution of any Licensee Application Software and by the implicit distribution and usage of any such functionality when linked into a software application program. The grant of license for the Licensed Software does not permit Licensee to either use or reproduce and distribute any files supplied as part of the Licensed Software in order to create a compiler, interpreter or runtime support product. Licensor offers specific production licensing options for distribution to third parties which vary depending upon the license fees paid by Licensee and Licensee should contact its Licensor sales representative for more details.

MAINFRAME EXPRESS® ENTERPRISE EDITION.

  1. Where Mainframe Express Enterprise Edition (all versions and editions including earlier versions such as Mainframe Express) is the Licensed Software, Mainframe Express Enterprise Edition may only be used for development purposes. Licensee may not use Mainframe Express Enterprise Edition for production purposes nor utilize or access any of the Mainframe Access portions of the Licensed Software from any Licensed Software product licensed separately, unless the Licensor product, Mainframe Access, has also been separately licensed from Licensor, in which case, the Mainframe Access product included as part of Mainframe Express Enterprise Edition may be installed on the number of host (mainframe) machines needed to support the number of authorized end-users of Mainframe Express Enterprise Edition.
  2. Where Mainframe Express Enterprise Edition is the Licensed Software, the Licensed Software will contain Component Generator. In order to use the components created using Component Generator, Licensee must pay a license fee. Upon payment of such license fee, Licensor grants Licensee a personal, non-exclusive, non-transferable license to use the components according to the type of license granted. Licensor has and will retain all ownership rights to any application source code generated by a template, wizard or similar functionality, (“Generated Source Code”) supplied as part of the Component Generator including without limitation all patent rights, copyrights, trademarks, trade secrets, service marks, related goodwill, and confidential and proprietary information relating thereto. For the avoidance of doubt, Generated Source Code does not include Application Server Files. Licensee shall have and retain all ownership rights to Licensee’s implementation of the Generated Source Code, provided that nothing in this Section shall be construed as in any way granting Licensee any right to limit or prevent: (i) Licensor from licensing any of its existing or future Licensed Software or providing any of its existing or future services to third parties; or (ii) Licensor or any other users of the Component Generator from generating and using identical or similar implementations of Generated Source Code. Licensor grants Licensee a perpetual, transferable, non-exclusive, royalty-free right to reproduce and distribute the Generated Source Code in object code form together with any implementation Licensee make thereto as a part of Licensee’s application of the Licensed Software product created using the Component Generator and that such Licensee application of the Licensed Software product adds significant and primary functionality to the Generated Source Code.

ALL VERSIONS OF MICRO FOCUS STUDIO, REUZE DEVELOPER AND NET EXPRESS. For this Licensed Software

  1. Redistribution of Internet Shortcut Support DLL (URL.DLL) in Microsoft Win32 SDK. To obtain rights to distribute file "URL.DLL" supplied as part of the Microsoft Win32 SDK that may be included with the Licensed Software, Licensee must print out, sign and return the Microsoft Win32 SDK End User Licensee Software License Agreement (located at \license\win32sdk.txt in the Microsoft Win32 SDK) to Microsoft Corporation, Win32 SDK Program, Building 5-2, One Microsoft Way, Redmond, Washington 98052-6399. URL.DLL may be included as part of a future version of Windows or Windows NT. Upon notification by Microsoft of its inclusion of URL.DLL in Windows or Windows NT, Licensee shall upgrade its application so that it no longer contains URL.DLL, and within a reasonable period after such time, but no later than six (6) months, cease distribution of URL.DLL.
  2. Use of Microsoft Visual Studio Technology and Visual Studio .NET Premier Partner Edition, including VSIP-SDK (“VSN Software”). The VSN Software is provided by and governed under the VSN Software End User License Agreement (“VSN EULA”) enclosed with the Licensed Software. Licensee must agree to be bound by the VSN EULA before use of the VSN Software. Licensee shall not use or enable others to use the information/content of the VSIP-SDK to enable any development environment other than Visual Studio .NET to host packages that use the interfaces documented in the VSIP-SDK or use or enable others to develop or distribute extensions to or wrappers for the VSN Software, or the interfaces between the Licensed Software and the VSN Software.

ACADEMIC EDITIONS/USERS. Where Licensed Software is licensed under Licensor’s ACTION Program, in addition to the above terms and conditions:

  1. Licensee shall not use the Licensed Software for any purpose other than for education, training or academic research activities.
  2. Licensee shall not copy the Licensed Software, nor shall Licensee distribute, transfer or assign the Licensed Software without specific permission from Licensor.
  3. License management: If Licensee is the academic institution using the Licensed Software for teaching purposes, Licensee will manage all student licenses through a license server provided by Licensor in accordance with guidelines provided by Licensor. Licensee agrees to provide reports describing the number of licenses Licensee has issued in each period upon Licensor’s request.
  4. Where CALIBERRM™, TEAMDEFINE™, TOGETHER®, STARTEAM®, TEMPO™, TEAMDEMAND®, TEAMFOCUS™, TEAMANALYTICS®, TEAMINSPECTOR™, SILKCENTRAL®, TEST MANAGER™, SILKTEST®, SILK4J™, SILKPERFORMER® APPSERVER™ OR VISIBROKER is the Licensed Software, the Licensed Software may be used solely for Licensee’s personal use in providing or receiving instruction within the limited scope of guided computer programming and/or software training course(s) in which Licensee is a direct and personal participant, either as student or instructor (“Course(s)”). The Licensed Software may only be used with other participants of the Courses and then only for educational or training purposes. The Licensed Software may not be used for any commercial, business, governmental or institutional purpose of any kind, except to the extent Licensee is an instructor teaching a Course.

NET EXPRESS PERSONAL EDITION. Where Net Express Personal Edition is the Licensed Software, in addition to the above terms and conditions:

  1. Licensee shall not to use the Licensed Software for any purpose other than for personal educational and non-commercial activities. The Licensed Software may not be used for training or teaching purposes.
  2. Licensee shall not use the Licensed Software to compile source code for applications of more than two thousand, two hundred (2200) lines of procedural code (exclusive of lines containing comments and/or blanks) in any one (1) application or to deploy such application to any other machine.
  3. Licensee shall not copy the Licensed Software, nor shall Licensee distribute, transfer or assign the Licensed Software without specific permission from Licensor

ALL VERSIONS OF MICRO FOCUS STUDIO, NET EXPRESS, AND SERVER EXPRESS. This Licensed Software may include or generate limited licenses for Micro Focus Server, Application Server and/or Enterprise Server. If such licenses are included or generated, these limited licenses are provided solely for use by the Named User of the Licensed Software in order to unit test an application developed with any version of Micro Focus Studio, Net Express, or Server Express on the server used to develop the application and may not be used for system testing, production or deployment. Any use of this limited license outside of the development and unit testing of such applications is outside the scope of the license.

ALL VERSIONS OF MICRO FOCUS STUDIO, REVOLVE® ENTERPRISE EDITION, MAINFRAME EXPRESS, NET EXPRESS, AND MICRO FOCUS LICENSE SERVER. Licensee may use the Micro Focus License Server that accompanies the Licensed Software to generate request or access codes for Licensee’s use of the Licensed Software. Licensee may not use the Micro Focus License Server to generate multiple-user request of access codes for the Licensed Software unless Licensee has paid the appropriate license fees for each authorized user accessing the Licensed Software.

MICRO FOCUS STUDIO FOR COBOL DEVELOPERS AND MICRO FOCUS STUDIO ENTERPRISE EDITION. Where Micro Focus Studio is the Licensed Software, Licensee may utilize the Licensed Software on both the Windows platform and one UNIX platform, which will be designated on the Product Order. Use of the Licensed Software on a different UNIX platform than originally licensed or on more than one UNIX platform will require additional licenses and the payment of applicable license fees. Licensee may install the Licensed Software on more than one machine or Host Server, so long as the Licensed Software is only used by the same named user on each machine or Host Server.

MICRO FOCUS REVOLVE ENTERPRISE EDITION. Where Micro Focus Revolve Enterprise Edition is the Licensed Software, Licensee may only utilize the Licensed Software for its own internal benefit and may not use the Licensed Software to process third-party code or to generate reports to be delivered to a third-party for that third party’s benefit without first entering into a separate agreement with Licensor.

MICRO FOCUS DATA EXPRESS™. Where Micro Focus Data Express is the Licensed Software Licensee may utilize both the Data Subset Extraction and the Data Masking modules, however, Licensee may only use other modules that are expressly listed in the relevant Product Order and for which Licensee has paid the separate relevant license fee.

MICRO FOCUS ENTERPRISE VIEW™. Where Micro Focus Enterprise View is the Licensed Software, Licensee may only use those additional modules that are listed in the Product Order and for which Licensee has paid a separate license fee. Where a Micro Focus Enterprise View module has language-specific capability, any licensed languages shall be listed in the Product Order. Support for additional languages is subject to an additional license fee.

MICRO FOCUS ENTERPRISE VIEW - RAPID ASSESSMENT OPTION. Micro Focus Enterprise View – Rapid Assessment Option is provided to Licensee on a fixed term license basis only. The start and ending dates of the term will be set forth in the Product Order. Unless otherwise stated in the Product Order, Micro Focus Enterprise View – Rapid Assessment Option is licensed on a “Line of Code” basis.

MODERNIZATION WORKBENCH SOFTWARE DEVELOPMENT KIT. This Licensed Software may only be utilized for the purpose of creating applications designed to operate with Modernization Workbench. The SDK does not contain any redistributable code and Licensee is not permitted to distribute any part of the SDK. No support is provided for the SDK.

XCENTRISITY BUSINESS INFORMATION SERVER. This Licensed Software is licensed on a concurrent user basis for local area network usage (“LAN”) or wide area network usage (“WAN”). A LAN license may only be installed and used on one server, whereas a WAN license may be installed and used on any number of servers, both subject to the number of concurrent users licensed.

OPTIMAL TRACE, QACENTER, QADIRECTOR, QALOAD, QARUN, RECONCILE, TESTPARTNER, TRACKRECORD, CARS, TEST FACTORY, DEVPARTNER. This Licensed Software may include technology for monitoring authorized use, including the policy files and license keys required to use the Licensed Software (the “License Authorization Server” or “LAS”). The LAS may be installed on a single-specified computer system at the specific site for which Licensee has contracted (the “Designated System”). The LAS, or any part thereof, may not be transferred from the Designated System. Regardless of the installation of the LAS, Licensee must remain compliant with the terms in this License Agreement (including without limitation any license restrictions and number of users permitted pursuant to this License Agreement). The LAS cannot be used or installed on a Virtual Machine.

Licensee may not transfer, ship or use this Licensed Software outside the country in which it was originally licensed to Licensee. Only one copy of the Licensed Software may be installed on a single computer at any one time unless: (A)The Software is designed and intended by Licensor for use in a shared network client server environment, as set forth in the Documentation; or (B) Licensee has purchased a license for each individual user of the Licensed Software and/or for each computer that will have access to the Software. Except for Optimal Trace Enterprise Edition, in the event the Software is designed and intended by Licensor for use in a shared network client server environment, Licensee may only install the Software on a single server.

The following shall only apply if the Licensed Software is device driver development software, used by Licensee to develop application or device driver programs (“User Software”), as specified in the Documentation. The User Software may include run-time components (“RTCs”) that have been extracted by the Software from the library files of the Software, programs to remotely test the User Software, and compiled code examples. These RTCs, examples, and programs are specifically designated as redistributable in the Documentation. Licensee has a worldwide, non-exclusive, royalty-free, restricted license to: (A) modify, compile and distribute the driver code examples; (B) distribute the remote testing program for testing purposes only; (C) embed the RTCs and driver code examples in its User Software, in object code form only; and (D) reproduce and distribute the RTCs and driver code examples embedded in its User Software, in object code form only provided that with respect to each of (A) – (D) inclusive (i) Licensee distributes the RTCs and driver code examples only in conjunction with and as a part of its User Software; (ii) Licensee will be solely responsible to anyone receiving its User Software for any updates, technical and other support obligations, and any other liability which may arise from the distribution of its User Software; (iii) Licensee does not use Licensor’s or its licensors' names, logos, or trademarks to market or distribute its User Software; (iv) Licensee includes Licensor’s and its licensors' copyright and/or proprietary notices and legends within the executable images of its User Software and on Licensee's software media and documentation; and (v) Licensee agrees to indemnify, hold harmless and defend Licensor and its licensors from and against any claims or lawsuits, including attorneys’ fees, that arise or result from the use or distribution of its User Software.

OPTIMAL TRACE, QACENTER, QADIRECTOR, QALOAD, QARUN, QUALITY MANAGER, RECONCILE, TESTPARTNER, TRACKRECORD, TEST FACTORY, DEVPARTNER. This Licensed Software may be used in a Virtual Machine only where licensed for concurrent users. In addition this Licensed Software may be used on any operating system on which the Licensed Software is capable of operating and which is supported by Licensor.

QALOAD. This Licensed Software may be licensed on a Virtual User basis. A "Virtual User" represents a simulation of a particular individual user executing a transaction or sequence of operations. QALoad Virtual users are pooled for use by the total number of licensed QALoad Conductors and one or more licensed QALoad Conductors may use some or all licensed Virtual Users. Virtual Users may be used across all support protocols (Easyscripts).

SILKCENTRAL, TEST MANAGER, SILKTEST, SILK4J, SILKPERFORMER This Licensed Software may include technology for monitoring authorized use, including the policy files and license keys required to use the Licensed Software (the “License Authorization Server” or “LAS”). The LAS may be installed on a single-specified computer system at the specific site for which Licensee has contracted (the “Designated System”). The LAS, or any part thereof, may not be transferred from the Designated System. Regardless of the installation of the LAS, Licensee must remain compliant with the terms in this License Agreement (including without limitation any license restrictions and number of users permitted pursuant to this License Agreement). The LAS cannot be used or installed on a Virtual Machine.

SILK PERFORMER. This Licensed Software may be installed on a reasonable number of Licensee computer systems. Licensee may use the Multi-Machine Controller (also referred to as “Workbench”) (“MMC”) component and related load-test agents on an unlimited number of machines for an unlimited number of users, but solely in connection with the use of SilkPerformer in accordance with the number, type and class of Virtual User Licenses purchased. Premium Virtual User Licenses for SilkPerformer, when ordered in any quantity, include a single Named User limited license to use SilkTest (the “Additional Product”). The Additional Product may be used ONLY in conjunction with the Premium Virtual User Licenses of SilkPerformer and may not be used or transferred on a stand-alone basis. Incremental use of any Additional Product beyond the single Named User license, or stand-alone use, must be licensed and paid for separately.

TEAMANALYTICS 2008. This Licensed Software includes a single Named User limited license to use StarTeam (either StarTeam Enterprise 2006, StarTeam Enterprise Advantage 2006, StarTeam Enterprise 2008 or StarTeam Enterprise Advantage 2008), CaliberRM (either CaliberRM 2006 or CaliberRM 2008) and SilkCentral Test Manager (either SilkCentral Test Manager 2006 or SilkCentral Test Manager 2008) (the “Additional Products”). The Additional Products may be used only in conjunction with the TeamAnalytics 2008 product and may not be used or transferred on a stand-alone basis. Incremental use of any Additional Products beyond the single Named User license, or stand-alone use, must be licensed and paid for separately.

TEAMANALYTICS 2009. This Licensed Software includes a single Named User limited license to use StarTeam, CaliberRM and SilkCentral Test Manager (collectively, the “Additional Products”). The Additional Products may be used ONLY in conjunction with the TeamAnalytics 2009 and may not be used or transferred on a stand-alone basis. Incremental use of any Additional Products beyond the single Named User license, or stand-alone use, must be licensed and paid for separately.

TOGETHER. This Licensed Software may be used solely to create, compile (including byte code compile), test and deploy, in source or object code form, Licensee application programs and other works. This Licensed Software requires registration with Licensor prior to use. Licensee will be prompted to register at the time of installation or first use, at which time Licensee will be notified, or directed to online resources explaining, how registration information provided by Licensee may be used and Licensee will be afforded the opportunity to opt out of certain uses of such information. Licensee may use the License Manager component of the Licensed Software, in executable form only, on a server for use solely in connection with Licensee’s use of the Licensed Software.

TEAMDEFINE. This Licensed Software includes the capability for an unlimited number of users to review the simulation program integrated into the Licensed Software by Licensor or its suppliers. Such users may not otherwise use the Licensed Software. Where an evaluation license option is obtained for this Licensed Software pursuant to Annex 1.E.2 the evaluation period will continue for up to 365 days. During the first 30 days of the evaluation period Licensee will be able to access all functionality of this Licensed Software except “Project Export”. During the remaining evaluation period such functionality will continue except that Licensee will have read only access to “simulations”, “requirements”, “SDK”, “integrations”, “images” and “templates”. Licensee may purchase a full license for this Licensed Software at any time during the evaluation period.

SILKCENTRAL, TEST MANAGER, SILKTEST, SILK4J, SILKPERFORMER, TEAMDEFINE, CALIBER™, TOGETHER, STARTEAM, TEMPO, TEAMDEMAND, TEAMFOCUS, TEAMANALYTICS, TEAMINSPECTOR, APPSERVER, VISIBROKER. This Licensed Software may be used in a Virtual Machine only where a concurrent user license has been granted

APPSERVER, VISIBROKER. For this Licensed Software, regardless of the number of CPU's for which Licensee has purchased a Deployment License: (i) Licensee may not run more than one instance of the deployed Licensed Software on a single computer, and (ii) the Licensed Software may not be accessed at any one time by more than the number of Concurrent Users indicated in the applicable Product Order. In the event Licensee desire additional instances or additional Concurrent Users, Licensee must purchase a separate license applicable to a different computer.

APPLICATION MIDDLEWARE PRODUCTS. Licensee may not include this Licensed Software or any component thereof in any general-purpose software development tool, library, component, or any other product that is generally competitive with or a substitute for the Licensed Software or any other Licensor product offerings; nor may Licensee use the Licensed Software to create a product or operate a service that is generally competitive with the Licensed Software or any other Licensor product offerings, including any general-purpose software development tool. The foregoing restriction does not apply, however, to use of the Licensed Software to develop "plug-ins" (i.e., integrations created using the Licensed Software's open tools API) so long as such plug-ins are designed to provide supplementary functionality to the Licensed Software.

This Licensed Software is not redistributable. Licensee is not permitted to reproduce the Licensed Software for sublicensing, resale, lending, leasing, deployment or distribution to any party, including without limitation, distributing the Licensed Software as part of a VAR, OEM, distributor or reseller arrangement. If Licensee integrates the Licensed Software into a Work and intends to distribute or resell the resulting integrated Work, Licensee must contact Licensor to obtain the appropriate distribution license.

The portions of this Licensed Software identified as VISISECURE, VISITRANSACT, VISINOTIFY, VISITIME and VISITELCOLOG (collectively, the " VISISERVICES") are not redistributable. This License Agreement does not permit Licensee to execute, or otherwise use the VISISERVICES portion of the Licensed Software for any purpose unless Licensee has acquired a separate Development and/or Deployment License for VISISERVICES directly from Licensor before developing or deploying any Work that uses such portion of the Licensed Software. Licensee is not permitted to reproduce VISISERVICES for sublicensing, resale, lending, leasing, deployment or distribution to any party, including without limitation, distributing VISISERVICES as part of a VAR, OEM, distributor or reseller arrangement. If Licensee integrates VISISERVICES into a Work and intends to distribute or resell the resulting integrated Work, Licensee must contact Licensor to obtain the appropriate distribution license.

Notwithstanding the prohibition hereunder against decompiling this Licensed Software, Licensee may use that portion of the Licensed Software identified as "API Decompiler" for inspecting the public application programming interface (API) of the JAVA BEANS COMPONENT LIBRARY, DATAEXPRESS, DBSWING and OPENTOOLS API modules.

The following Java Technology Restrictions are applicable to the component of this Licensed Software identified as SonicMQ if it accompanies the Licensed Software: Licensee may not modify the Java Platform Interface ("JPI", identified as classes contained within the "java" package or any subpackages of the "java" package), by creating additional classes within the JPI or otherwise causing the addition to or modification of the classes in the JPI. In the event that Licensee otherwise create an additional class and associated API(s) which (i) extends the functionality of a Java platform, and (ii) is exposed to third party software developers for the purpose of developing additional software which invokes such additional API, Licensee must promptly publish broadly an accurate specification for such API for free use by all developers. Licensee may not create, or authorize its own licensees to create additional classes, interfaces, or subpackages that are in any way identified as "java", "javax", "sun" or similar convention as specified by sun in any class file naming convention.

This Licensed Software may include certain files, libraries and/or source code specifically designated as “redistributables" by Licensor in the accompanying printed or on-line documentation and that are necessary to use works created using the Product ("Redistributables"). From time to time, Licensor may designate other files as Redistributables. Subject to the terms and conditions of this License Agreement, Licensee may freely redistribute source code or compiled code that is entirely Licensee’s own and does not contain any Redistributables. Subject to the terms and conditions of this License Agreement, Licensor grants Licensee the personal, non-exclusive, non-transferable and limited license to: (a) make exact copies of the Redistributables and distribute those copies solely as components of Licensee’s Works and solely as required for permitting end users of the Works ('End users") to install and execute the Works; (b) install and execute Redistributables, without modification, solely for Licensee’s own internal use; and (c) sublicense to End Users the personal, non-exclusive, non-transferable right to install and execute Redistributables, without modification, solely as components of Works and solely for such End Users' own internal use, subject to End Users' compliance with the restrictions in this License Agreement. These rights granted may not be exercised by others, including co-developers, regardless of how Licensee’s Works are compiled, linked, or packaged. These rights apply only to Redistributables and to no other file, library, source code or other component or derivative work of the Licensed Software. They may be exercised only with respect to works created by Licensee using a duly licensed, properly registered copy of the Licensed Software.

ENDS

END USER LICENSE AGREEMENT SUPPLEMENT

The following terms and conditions shall supersede any conflicting terms and conditions set forth elsewhere in the End User License Agreement:

Where Licensor has expressly granted to Licensee the right to install and use the Licensed Software on a soft partition, the license fee shall be based on an "expected" Cores number calculated as the ratio of the number of Cores allocated to the soft partition to the total number of Cores on the Host Server, increased by a percentage to be determined by Licensor. To be effective, such grant must be set forth in the applicable Product Order or otherwise in writing separate from this License Agreement.

END USER LICENSE AGREEMENT SUPPLEMENT

The following terms and conditions shall supersede any conflicting terms and conditions set forth elsewhere in the End User License Agreement:

With respect to Micro Focus COBOLTM 2010 Runtime, COBOL Server, and all other application deployment products, Licensee may reproduce and distribute internally, in whole or in part, subject to the applicable license option as described in Annex 1 and the applicable Product Order, any software application program created by Licensee using the corresponding development product for the Licensed Software (if separately licensed to Licensee by Micro Focus) that contains any files from such development product and/or the Licensed Software ("Licensee Application Software"). Licensee shall (a) include Licensor's copyright notice for the Licensed Software on any product label and as a part of any sign-on message for such Licensee Application Software product; and (b) indemnify, hold harmless and defend Licensor and its third-party suppliers from and against any claims or lawsuits, including attorneys' fees, legal fees and court costs that arise out of, or result from, the use or distribution of such Licensee Application Software. Licensee can only reproduce and distribute Licensee Application Software to third parties after entering into a separate distribution agreement with Licensor. Usage and distribution of the Licensee Application Software arises both by the explicit distribution of any Licensee Application Software and by the implicit distribution and usage of any of the Licensee Application Software's functionality when linked into another software application program. The grant of license for the Licensed Software does not permit Licensee to either use or reproduce and distribute any files supplied as part of the Licensed Software in order to create a compiler, interpreter or runtime support product. Licensor offers specific production licensing options for distribution to third parties which vary depending upon the license fees paid by Licensee and Licensee should contact its Licensor sales representative for more details.

With respect to all application development products including Visual COBOL®:

  1. Licensee shall not use the Licensed Software, nor reproduce or distribute any files supplied as part of the Licensed Software, in order to create a compiler, interpreter, runtime support product or any other product that is generally competitive with or a substitute for the Licensed Software or any other Licensor product.
  2. This Licensed Software may include or generate limited licenses for Micro Focus COBOLTM 2010 Runtime, COBOL Server, or other deployment product. If such licenses are included or generated, these limited licenses are provided solely for use by the Named User of the Licensed Software in order to unit test an application developed with the Licensed Software on the same machine or server used to develop the application and may not be used for system testing, production or deployment, and (for Visual COBOL® products) may only be used if the Licensed Software is current on support and maintenance. Any use of this limited license outside of the development and unit testing of such applications is not permitted.

With respect to VISUAL COBOL® PERSONAL EDITION products:

  1. Licensee shall not use the Licensed Software for any purpose other than for personal educational and non-commercial activities. The Licensed Software may not be used for training or teaching purposes, and
  2. Licensee shall not use the Licensed Software to compile source code for applications of more than two thousand, two hundred (2200) lines of procedural code (exclusive of lines containing comments and/or blanks) in any one (1) application or to deploy such application to any other machine.

END USER LICENSE AGREEMENT SUPPLEMENT

The following terms and conditions shall supersede any conflicting terms and conditions set forth elsewhere in the End User License Agreement:

With respect to Enterprise Developer PERSONAL EDITION products:

  1. Licensee shall not use the Licensed Software, nor reproduce or distribute any files supplied as part of the Licensed Software, in order to create a compiler, interpreter, runtime support product or any other product that is generally competitive with or a substitute for the Licensed Software or any other Licensor product.
  2. The compiler functionality in the Licensed Software has been disabled. Licensee shall not use the Licensed Software for any purpose other than to input, edit and syntax check code for personal educational use. The Licensed Software may not be used for training or teaching purposes.
Micro Focus License Agreement 1 November 2009 All products LIC-GEN-17Supp1, 2.1, ED PE
Parent topic: Product Information


Third Party Software

These third party products may be required by the software in order to provide full functionality. In most cases you will need to obtain and install them individually.

  • Database Access Support
  • Java Development Kit (JDK)
Parent topic: Product Information


Database Access Support

Before you can use this product to deploy SQL applications developed with COBSQL, DB2 ECM or OpenESQL, ensure any third party software prerequisites are installed and the environment is set properly. Refer to the Visual COBOL documentation, Programming > Database Access for details.

Parent topic: Third Party Software


Java Development Kit (JDK)

The Java Development Kit (JDK) is required for compiling Java.

JDK or JRE is required for compiling and running COBOL JVM applications

After installing the JDK, you need to set up your Java environment.

Parent topic: Third Party Software


Known Errors and Restrictions

The following known errors and restrictions apply to COBOL Server:

  • File Handler
  • Run-Time System
Parent topic: Product Information


File Handler

The IDXNAMETYPE file-handler configuration option does not work correctly when used in a managed .NET application and the filename (including the specified path) of the file being opened includes one or more space characters. The file will not be opened and an error file-status or RTS error message will be generated.

Parent topic: Known Errors and Restrictions


Run-Time System

Memory corruption detected

The run-time system error COBRT252 "Memory corruption detected (Fatal)", might occur when performing a SORT FIELDS=COPY on a file with a record format of VB, under mainframe emulation of DFSORT.

-542609

Threaded Programs - Return Code

If you create a multi-threaded application that uses CBL_EXIT_PROC to perform an exit procedure when the program terminates, and an error occurs during the exit procedure, the application does not terminate with a non-zero exit code to the operating system.

Parent topic: Known Errors and Restrictions


Contacting Micro Focus

Our Web site gives up-to-date details of contact numbers and addresses.

  • Further Information and Product Support
  • Information We Need
Parent topic: Product Information


Further Information and Product Support

Additional technical information or advice is available from several sources.

The product support pages contain a considerable amount of additional information, such as:

  • The WebSync service, where you can download fixes and documentation updates.
  • The Knowledge Base, a large collection of product tips and workarounds.
  • Examples and Utilities, including demos and additional product documentation.

To connect, enter http://www.microfocus.com in your browser to go to the Micro Focus home page.

Note: Some information may be available only to customers who have maintenance agreements.

If you obtained this product directly from Micro Focus, contact us as described on the Micro Focus Web site, www.microfocus.com. If you obtained the product from another source, such as an authorized distributor, contact them for help first. If they are unable to help, contact us.

Parent topic: Contacting Micro Focus
Related information
Knowledge Base
Examples and Utilities
Community Forums
White Papers and Webcasts


Information We Need

However you contact us, please try to include the information below, if you have it. The more information you can give, the better Micro Focus SupportLine can help you. But if you don't know all the answers, or you think some are irrelevant to your problem, please give whatever information you have.

  • The name and version number of all products that you think might be causing a problem.
  • Your computer make and model.
  • Your operating system version number and details of any networking software you are using.
  • The amount of memory in your computer.
  • The relevant page reference or section in the documentation.
  • Your serial number. To find out these numbers, look in the subject line and body of your Electronic Product Delivery Notice email that you received from Micro Focus.

Alternatively, you might be asked to provide a log file created by the Consolidated Tracing Facility (CTF) - a tracing infrastructure that enables you to quickly and easily produce diagnostic information detailing the operation of a number of Micro Focus software components.

On UNIX, you can use the Micro Focus UNIX Support Scan Utility, mfsupport, to create a log file that contains the details about your environment, product, and settings. The mfsupport script is stored in $COBDIR/bin.

To run mfsupport:

  1. Start a UNIX shell.
  2. Set COBDIR to the product with issues.
  3. Execute mfsupport from a directory where you have write permissions.

    This creates a log file, mfpoll.txt, in that directory.

  4. When the script finishes, send the mfpoll.txt file to your Micro Focus SupportLine representative.
Note:

If COBDIR is set to a location which does not contain etc/cobver, the script outputs the contents of /opt/microfocus/logs/MicroFocusProductRegistry.dat which keeps a list of the installed Micro Focus products.

Parent topic: Contacting Micro Focus


Managing Licenses

To manage your product licenses you need to use the Micro Focus Licensing Administration tool. The tool allows you to authorize, view and revoke licenses. You can set up your license locally or request a license from, if your site is using one, a central license server.

Depending on your product configuration, you might, when you first install your product, have a trial license. During this period, if you have not already authorized your product with your authorization code, a dialog box will be displayed on product startup providing the opportunity to authorize your product. You can use the Micro Focus Licensing Administration tool to find out how many days remain on your license. You will not be able to use your product if, at the end of the trial license period, you have not authorized it with your authorization code.

If your product does not have a trial license, you must authorize it before you can use it.

For more on the Micro Focus Licensing Administration Tool, see Licensing in the Visual COBOL help.

Parent topic: Welcome
Related concepts
Welcome
Licensing


Running an Application from the Command Line

Runnable programs can be linked system executable files, which can be run directly from the command line, or dynamically loadable programs, which can be run without being linked into a system executable file.

  • Command to Run a Linked System Executable Program
  • cobrun Command
Parent topic: Micro Focus COBOL Server for UNIX


Command to Run a Linked System Executable Program

To run a linked system executable program, enter the following command:

program-name [parameters]

where:

program-name
The name of a system executable file. If the program-name does not contain an explicit path then the directories specified by the $PATH environment variable are searched.
parameters
Parameters that are required by the program. Each parameter is a string, separated from adjoining parameters by one or more spaces. There must be at least one parameter.
Parent topic: Running an Application from the Command Line


cobrun Command

To run dynamically loadable programs (that is, callable shared objects or .gnt files or .int files) use the command cobrun (or cobrun_t for multi-threaded programs) as follows:

cobrun [switch-param] program-name [program-param]

where:

switch-param
One or more programmable and run-time switches that control events in a program at run time. Your application supplier will tell you which switches to specify.
program-name
The name of a dynamically loadable program.
If you do not specify an explicit filename extension in the cobrun command, and multiple versions exist, then by default:
  • The callable shared object version is run in preference to the .gnt file
  • The .gnt file is run in preference to the .int file.

If program-name does not contain an explicit path the directories specified by $COBPATH, and in the case of a callable shared object, the directories specified by $LD_LIBRARY_PATH, $LIBPATH, or $SHLIB_PATH are searched.

program-parameters
One or more parameters that are required by the program. Each parameter is a string, separated from adjoining parameters by one or more spaces.

If any of the parameters contain an equal sign, the equal sign is mapped to parentheses as these have a special meaning to UNIX, whereas the equal sign does not. These parameters can be read by the program in a number of ways.

Parent topic: Running an Application from the Command Line


Run-time System Error Messages

These messages are output by the run-time system (RTS), and so can be produced while you are compiling, debugging, or running your program. When you select an error message number, its text and severity is listed, along with an explanation of the error or problem that caused the message, and advice on how to prevent the error.

  • Key to Run-time System Error Messages
  • COBRT001 - COBRT020
    Lists the Run-time System error messages from COBRT001 through COBRT020.
  • COBRT021 - COBRT040
    Lists the Run-time System error messages from COBRT021 through COBRT040.
  • COBRT041 - COBRT060
    Lists the Run-time System error messages from COBRT041 through COBRT060.
  • COBRT061 - COBRT080
    Lists the Run-time System error messages from COBRT061 through COBRT080.
  • COBRT101 - COBRT120
    Lists the Run-time System error messages from COBRT101 through COBRT120.
  • COBRT121 - COBRT140
    Lists the Run-time System error messages from COBRT121 through COBRT140.
  • COBRT141 - COBRT160
    Lists the Run-time System error messages from COBRT141 through COBRT160.
  • COBRT161 - COBRT180
    Lists the Run-time System error messages from COBRT161 through COBRT180.
  • COBRT181 - COBRT200
    Lists the Run-time System error messages from COBRT181 through COBRT200.
  • COBRT201 - COBRT220
    Lists the Run-time System error messages from COBRT201 through COBRT220.
  • COBRT221 - COBRT240
    Lists the Run-time System error messages from COBRT221 through COBRT240.
  • COBRT241 - COBRT260
    Lists the Run-time System error messages from COBRT241 through COBRT260.
Parent topic: Micro Focus COBOL Server for UNIX


Key to Run-time System Error Messages

These messages are output by the run-time system (RTS), and so can be produced while you are compiling, debugging, or running your program. When you select an error message number, its text and severity is listed, along with an explanation of the error or problem that caused the message, and advice on how to prevent the error.

Run-time system error messages have the following format:

ErrorCode Description

where the parameters are:

ErrorCode A code containing the following information:
  • The component that the error occurred in.
  • The operation that was taking place when the error occurred.
  • The error message number.
Description A description of the cause of the error.

There are two types of run-time error:

Fatal | A message is sent to the screen and the program terminates immediately.
Recoverable | The error is reported to the program. You can trap these errors in your program, but often they are the result of an error in your program's logic. If the program does not trap the error a message is sent to the screen and the program terminates immediately.
Parent topic: Run-time System Error Messages


COBRT001 - COBRT020

  • COBRT001 Insufficient buffer space (Recoverable)
    You have tried to open a file directly or indirectly and, although you have not exceeded your system's file limit, something in your system is unable to allocate enough memory space for this operation.
  • COBRT002 File not open when access attempted (Recoverable)
    You have tried to access a file without opening it first.
  • COBRT003 Serial mode error (Recoverable)
    You have tried to open a device as a relative or indexed file.
  • COBRT004 Illegal file name (Recoverable)
    A file-name contains an illegal character. This could be any character that is not part of the permitted character set or it could be the system-dependent delimiter, which on most systems is the space.
  • COBRT005 Illegal device specification (Recoverable)
    Devices to which your COBOL program can write are defined by the operating system. You have tried to write to a device that is not defined by your system.
  • COBRT006 Attempt to write to a file opened for INPUT (Recoverable)
    You have tried to WRITE to a file that is open for input only.
  • COBRT007 Disk space exhausted (Fatal)
    The disk is full.
  • COBRT008 Attempt to input from a file opened for OUTPUT (Recoverable)
    You have tried to read from a file that is open for output only.
  • COBRT009 Directory not found (Recoverable)
    The system cannot write to the specified directory for one of the following reasons:
  • COBRT010 File name not supplied (Recoverable)
    You have tried to open a file that you have declared as an external file, but have not named.
  • COBRT011 Process limit reached (Fatal)
    One of the following has occurred:
  • COBRT012 Attempt to open a file which is already open (Recoverable)
    You have tried to open a file which is already open and so cannot be opened again.
  • COBRT013 File not found (Recoverable)
    The operating system has been unable to find a file which you have tried to access in your program.
  • COBRT014 Too many files open simultaneously (Recoverable)
    You have tried to exceed the maximum number of files which you can have open at any one time. This can be a software or an operating system constraint, but you must not violate it.
  • COBRT015 Too many indexed files open (Recoverable)
    You have tried to exceed the maximum number of indexed files which you can have open at any one time. This can be a software or an operating system restraint, but you must not violate it.
  • COBRT016 Too many device files open (Recoverable)
    You have tried to exceed the maximum number of device files which you can have open at any one time. This can be a software or an operating system constraint, but you must not violate it.
  • COBRT017 Record error: probably zero length (Recoverable)
    You have probably tried to access a record that has had no value moved into it.
  • COBRT018 Read part record error: EOF before EOR or file open in wrong mode (Recoverable)
    A part record has been found at the end of a file. Consequently your run-time system treats the data file as a record, and not finding a full record, reports this error.
  • COBRT019 Rewrite error: open mode or access mode wrong (Recoverable)
    You are trying to do a REWRITE to a file that has not been opened with the correct access mode for this operation.
  • COBRT020 Device or resource busy (Recoverable)
    You have tried to open a file that is assigned to a device or resource (for example, a line printer) that is not available at this time.
Parent topic: Run-time System Error Messages


COBRT001 Insufficient buffer space (Recoverable)

You have tried to open a file directly or indirectly and, although you have not exceeded your system's file limit, something in your system is unable to allocate enough memory space for this operation.

Resolution:

Although you can trap this error you must do STOP RUN as soon as it is reported.

Parent topic: COBRT001 - COBRT020


COBRT002 File not open when access attempted (Recoverable)

You have tried to access a file without opening it first.

Resolution:

Open the file with the open mode that you need and try the operation again. As this error implies that your program logic contains a mistake, you might want to terminate the run and recode your program.

Parent topic: COBRT001 - COBRT020


COBRT003 Serial mode error (Recoverable)

You have tried to open a device as a relative or indexed file.

You are trying to execute a device, not a program.

Resolution:

Open the device in the correct mode or close any open files, do STOP RUN and recode your program.

The name of your program is recognized by the operating system as a valid device. Rename your program.

Parent topic: COBRT001 - COBRT020


COBRT004 Illegal file name (Recoverable)

A file-name contains an illegal character. This could be any character that is not part of the permitted character set or it could be the system-dependent delimiter, which on most systems is the space.

Resolution:

Try the file operation again using the correct file-name.

Parent topic: COBRT001 - COBRT020


COBRT005 Illegal device specification (Recoverable)

Devices to which your COBOL program can write are defined by the operating system. You have tried to write to a device that is not defined by your system.

Resolution:

Try the operation again using a device name that your system recognizes.

Parent topic: COBRT001 - COBRT020


COBRT006 Attempt to write to a file opened for INPUT (Recoverable)

You have tried to WRITE to a file that is open for input only.

Resolution:

Close the file and open it with a mode such as I-O, which allows you to write to the file. As this error implies that your program logic contains a mistake, you might want to terminate the run and recode your program.

Parent topic: COBRT001 - COBRT020


COBRT007 Disk space exhausted (Fatal)

The disk is full.

Resolution:

This error can be trapped, but once it has been reported you must do a STOP RUN immediately to terminate your program's run. When your program has terminated, delete any files that you no longer need. Alternatively, if your operating system supports this, put a new disk in a floppy disk drive and redirect your program's file operations to this.

Parent topic: COBRT001 - COBRT020


COBRT008 Attempt to input from a file opened for OUTPUT (Recoverable)

You have tried to read from a file that is open for output only.

Resolution:

Close the file and open it with a mode such as I-O, which allows you to read from the file. As this error implies that your program logic contains a mistake, you might want to terminate the run and recode your program.

Parent topic: COBRT001 - COBRT020


COBRT009 Directory not found (Recoverable)

The system cannot write to the specified directory for one of the following reasons:
  • The directory does not exist
  • The directory is full
  • Your program cannot find the directory

Resolution:

Create the directory if it doesn't exist. If the directory is full, either delete any files that you no longer need or, if your operating system supports this, put a new disk in a floppy disk drive and redirect your program's file operations to it. Alternatively, specify a different drive or directory for your file operations.

Parent topic: COBRT001 - COBRT020


COBRT010 File name not supplied (Recoverable)

You have tried to open a file that you have declared as an external file, but have not named.

Resolution:

Specify the external file-name.

Parent topic: COBRT001 - COBRT020


COBRT011 Process limit reached (Fatal)

One of the following has occurred:
  • The run-time system cannot create a new process as the operating system limit on the total number of processes per user or system-wide would be exceeded.
  • Insufficient memory is available to complete the operation.

Resolution:

Terminate any processes that you are no longer using, or make more memory available.

Your operating system might enable you to increase the maximum number of processes allowed. Refer to your operating system documentation for further information.

Parent topic: COBRT001 - COBRT020


COBRT012 Attempt to open a file which is already open (Recoverable)

You have tried to open a file which is already open and so cannot be opened again.

Resolution:

Cancel your second attempt to open the file. If the fact that the file is already open is acceptable to you, continue to run your program.

Parent topic: COBRT001 - COBRT020


COBRT013 File not found (Recoverable)

The operating system has been unable to find a file which you have tried to access in your program.

Resolution:

Ensure that you are in the correct directory or that a path to the file concerned exists. You can then try the file operation again. If the error is the result of a spelling mistake then ask for the correct file and try the file operation again.

Parent topic: COBRT001 - COBRT020


COBRT014 Too many files open simultaneously (Recoverable)

You have tried to exceed the maximum number of files which you can have open at any one time. This can be a software or an operating system constraint, but you must not violate it.

Resolution:

Close some of the open files which you are not currently accessing, and then try to open the relevant file again. You should then be able to continue to run your program.

Parent topic: COBRT001 - COBRT020


COBRT015 Too many indexed files open (Recoverable)

You have tried to exceed the maximum number of indexed files which you can have open at any one time. This can be a software or an operating system restraint, but you must not violate it.

Resolution:

Close some of the open indexed files which you are not currently accessing, and then try to open the relevant file again. You should then be able to continue to run your program. (Indexed files count as two files, one for data and one for the index.)

Parent topic: COBRT001 - COBRT020


COBRT016 Too many device files open (Recoverable)

You have tried to exceed the maximum number of device files which you can have open at any one time. This can be a software or an operating system constraint, but you must not violate it.

Resolution:

Close some of the open device files which you are not currently accessing, and then try to open the relevant file again. You should then be able to continue to run your program.

Parent topic: COBRT001 - COBRT020


COBRT017 Record error: probably zero length (Recoverable)

You have probably tried to access a record that has had no value moved into it.

Resolution:

Although this error is recoverable in the sense that it can be trapped, once it has been reported you must execute a STOP RUN statement immediately and then recode your program to ensure that the COBOL record length is not zero.

Parent topic: COBRT001 - COBRT020


COBRT018 Read part record error: EOF before EOR or file open in wrong mode (Recoverable)

A part record has been found at the end of a file. Consequently your run-time system treats the data file as a record, and not finding a full record, reports this error.

Resolution:

Ensure that the record size you give when you read from or WRITE to a file is consistent.

Parent topic: COBRT001 - COBRT020


COBRT019 Rewrite error: open mode or access mode wrong (Recoverable)

You are trying to do a REWRITE to a file that has not been opened with the correct access mode for this operation.

Resolution:

Close the file and reopen it in a mode such as I-O, which allows you to do REWRITE operations on that file. As this error implies that your program logic contains a mistake, you might want to close any open files and then execute a STOP RUN. You can then recode your program to eliminate the logic error.

Parent topic: COBRT001 - COBRT020


COBRT020 Device or resource busy (Recoverable)

You have tried to open a file that is assigned to a device or resource (for example, a line printer) that is not available at this time.

Resolution:

You can trap the error status returned by open and retry the open at regular intervals until it succeeds.

Parent topic: COBRT001 - COBRT020


COBRT021 - COBRT040

  • COBRT021 File is a directory (Fatal)
    You have tried to WRITE to a directory instead of to a file.
  • COBRT022 Illegal or impossible access mode for OPEN (Recoverable)
    The mode in which you are trying to open a file violates the General Rule of COBOL for that type of file; for example you might have opened a line sequential file in the I-O mode.
  • COBRT023 Illegal or impossible access mode for CLOSE (Recoverable)
    The mode in which you are trying to close a file is not possible for that type of file.
  • COBRT024 Disk input-output error (Recoverable)
    You might have performed a read after a WRITE, or there might be either a verification failure or a parity error.
  • COBRT025 Operating system data error (Fatal)
    You are trying to set up terminal characteristics for a device which is not a terminal.
  • COBRT026 Block I-O error (Fatal)
    An error has occurred while you are trying to access a disk. This could be the result of a corrupt disk.
  • COBRT027 Device not available (Recoverable)
    You are trying to access a device which either is not attached to your machine or if attached is not online.
  • COBRT028 No space on device (Fatal)
    You have tried a file operation such as WRITE for which insufficient space is available on your disk.
  • COBRT029 Attempt to delete open file (Recoverable)
    You have tried to perform a DELETE FD operation on an open file.
  • COBRT030 File system is read-only (Recoverable)
    The file system which you are using is read-only, which effectively means that it is write-protected. You have tried to change a file in some way, for example you might have tried to WRITE to a file or to DELETE information in it.
  • COBRT031 Not owner of file (Recoverable)
    You are trying an operation on a file but the file's owner has not given you the necessary permission for that operation. You could for example be trying to alter the access modes for a file, which only the file's owner can do.
  • COBRT032 Too many indexed files, or no such process (Recoverable)
    You have tried to open an indexed file but the number of files that you currently have open is the system limit.
  • COBRT033 Physical I-O error (Fatal)
    You have a hardware error of some type. Perhaps you have not put a disk in the relevant drive or you might have tried to WRITE to a disk but the processor detected hardware interface has failed.
  • COBRT034 Incorrect mode or file descriptor (Recoverable)
    You are either trying to write to a file which is open for read purposes only, or read a file which is open for write purposes only.
  • COBRT035 Attempt to access a file with incorrect permission (Recoverable)
    You are trying a file operation which you do not have sufficient permission to achieve. For example you could be trying to write data to a file which has been set up with the read attribute only.
  • COBRT036 File already exists (Recoverable)
    You are trying an inappropriate operation on an already existing file.
  • COBRT037 File access denied (Fatal)
    Your attempt to access a file has been denied by the operating system. You might have tried to write to a write-protected file or you could have tried to read from an output device.
  • COBRT038 Disk not compatible (Fatal)
    You have tried to access a disk that is incompatible with the current version of your operating system. This could be because it was created under a previous version of the system or it could have been created under a completely different operating system. You would also receive this error if you tried to load a disk with a name that clashed with a disk that was already loaded.
  • COBRT039 File not compatible (Fatal)
    You have tried to access a file that is not compatible with the structure of files under the current release of your software. This could be because the file was created either under a different operating system or under a previous version of your current system.
  • COBRT040 National Language initialization not set up correctly (Fatal)
    You have tried to use the additional language variants, but the environment or side file that is required to set up the language either has not been set up correctly, or does not exist, or is invalid.
Parent topic: Run-time System Error Messages


COBRT021 File is a directory (Fatal)

You have tried to WRITE to a directory instead of to a file.

Alternatively, the attributes are not set up correctly to allow you to access a file. That is, it is marked as read-only or you don't have sufficient rights to open it.

Resolution:

Recode your program so that it writes to a file and not to a directory.

You need to either change your file access attributes or recode your program so that it does not violate the existing attributes.

Parent topic: COBRT021 - COBRT040


COBRT022 Illegal or impossible access mode for OPEN (Recoverable)

The mode in which you are trying to open a file violates the General Rule of COBOL for that type of file; for example you might have opened a line sequential file in the I-O mode.

Resolution:

Open the file with a mode that is compatible with that type of file.

Parent topic: COBRT021 - COBRT040


COBRT023 Illegal or impossible access mode for CLOSE (Recoverable)

The mode in which you are trying to close a file is not possible for that type of file.

Resolution:

Close the file with a new access mode which is compatible with that type of file, or execute a STOP RUN statement and recode your program.

Parent topic: COBRT021 - COBRT040


COBRT024 Disk input-output error (Recoverable)

You might have performed a read after a WRITE, or there might be either a verification failure or a parity error.

Resolution:

In some circumstances this error is fatal, but if it occurs during a read you can trap it and then do a close on the file before executing a STOP RUN statement.

Parent topic: COBRT021 - COBRT040


COBRT025 Operating system data error (Fatal)

You are trying to set up terminal characteristics for a device which is not a terminal.

Resolution:

Recode your program.

Parent topic: COBRT021 - COBRT040


COBRT026 Block I-O error (Fatal)

An error has occurred while you are trying to access a disk. This could be the result of a corrupt disk.

Resolution:

If you have a corrupt disk try to run your program again using your backup copy.

Parent topic: COBRT021 - COBRT040


COBRT027 Device not available (Recoverable)

You are trying to access a device which either is not attached to your machine or if attached is not online.

Resolution:

Attach the device to your machine and ensure that it is online. Repeat the file operation.

Parent topic: COBRT021 - COBRT040


COBRT028 No space on device (Fatal)

You have tried a file operation such as WRITE for which insufficient space is available on your disk.

Resolution:

When your program has terminated you should delete some of the files or directories on your current logged in disk. Ensure that you delete sufficient files on your disk so that you have enough room to carry out successful file operations.

Parent topic: COBRT021 - COBRT040


COBRT029 Attempt to delete open file (Recoverable)

You have tried to perform a DELETE FD operation on an open file.

Resolution:

Close the file before performing the DELETE FD operation.

Parent topic: COBRT021 - COBRT040


COBRT030 File system is read-only (Recoverable)

The file system which you are using is read-only, which effectively means that it is write-protected. You have tried to change a file in some way, for example you might have tried to WRITE to a file or to DELETE information in it.

Resolution:

You should abandon your attempt to alter the file unless you can make your own personal copy of it. You should then be able to alter the contents of your copy, but not of the original source.

Parent topic: COBRT021 - COBRT040


COBRT031 Not owner of file (Recoverable)

You are trying an operation on a file but the file's owner has not given you the necessary permission for that operation. You could for example be trying to alter the access modes for a file, which only the file's owner can do.

Resolution:

You should abandon your tried file operation unless the file's owner gives you the permission necessary to do the operation you want to carry out.

Parent topic: COBRT021 - COBRT040


COBRT032 Too many indexed files, or no such process (Recoverable)

You have tried to open an indexed file but the number of files that you currently have open is the system limit.

Alternatively, you could be trying to use a process id which does not exist, or which your operating system no longer recognizes.

Resolution:

You should close some of the indexed files which you are no longer accessing, and you should then be able to open the file you require.

In this case you must rewrite your code so that it uses a process id which your system recognizes.

Parent topic: COBRT021 - COBRT040


COBRT033 Physical I-O error (Fatal)

You have a hardware error of some type. Perhaps you have not put a disk in the relevant drive or you might have tried to WRITE to a disk but the processor detected hardware interface has failed.

Resolution:

You should try to correct the fault in your hardware; for example put a disk in the necessary drive.

Parent topic: COBRT021 - COBRT040


COBRT034 Incorrect mode or file descriptor (Recoverable)

You are either trying to write to a file which is open for read purposes only, or read a file which is open for write purposes only.

Resolution:

You should close the file and reopen using the correct access mode. As this error implies that your program logic contains a mistake, you might want to close any open files, execute a STOP RUN statement and then recode your program to eliminate the logic error.

Shareable files opened INPUT (read-only) by the COBOL system still require write-permission (from the operating system) to enable temporary locking to take place.

Parent topic: COBRT021 - COBRT040


COBRT035 Attempt to access a file with incorrect permission (Recoverable)

You are trying a file operation which you do not have sufficient permission to achieve. For example you could be trying to write data to a file which has been set up with the read attribute only.

Resolution:

If you are the owner of the file you can alter the attributes of the file so that you have the permission needed to effect the particular file operation you were trying. If you are not the owner of the file you cannot to carry out that operation successfully unless you copy the file and make the changes to the copy only. You cannot alter the source file.

Parent topic: COBRT021 - COBRT040


COBRT036 File already exists (Recoverable)

You are trying an inappropriate operation on an already existing file.

Resolution:

Recode your program to eliminate this mistake.

Parent topic: COBRT021 - COBRT040


COBRT037 File access denied (Fatal)

Your attempt to access a file has been denied by the operating system. You might have tried to write to a write-protected file or you could have tried to read from an output device.

Resolution:

Alter the access permission on the relevant file. Access can be read-only, if you just want to read the contents of the file without making any changes, or it can be read and write in which case you can alter its contents.

Parent topic: COBRT021 - COBRT040


COBRT038 Disk not compatible (Fatal)

You have tried to access a disk that is incompatible with the current version of your operating system. This could be because it was created under a previous version of the system or it could have been created under a completely different operating system. You would also receive this error if you tried to load a disk with a name that clashed with a disk that was already loaded.

Resolution:

If the error is a result of a clash of names you can rename one of the disks and then you can load both disks together if this is what you want.

Parent topic: COBRT021 - COBRT040


COBRT039 File not compatible (Fatal)

You have tried to access a file that is not compatible with the structure of files under the current release of your software. This could be because the file was created either under a different operating system or under a previous version of your current system.

Resolution:

You should create a new copy of the file which has the correct structure.

Parent topic: COBRT021 - COBRT040


COBRT040 National Language initialization not set up correctly (Fatal)

You have tried to use the additional language variants, but the environment or side file that is required to set up the language either has not been set up correctly, or does not exist, or is invalid.

This might be because you have the LANG environment variable set for use by another system in a format not recognized by this COBOL system.

Resolution:

Set up the required environment or side file before you try to run the program again.

Parent topic: COBRT021 - COBRT040


COBRT041 - COBRT060

  • COBRT041 Corrupt index file (Recoverable)
    Your run-time system does not recognize the control information for an indexed file and as the index has been corrupted in some way the data in the file is no longer accessible by your system. This error is recoverable in the sense that it can be trapped but should you receive it, you can do little except to close any open files and stop your program's run.
  • COBRT042 Attempt to write on broken pipe (Recoverable)
    One of the following has occurred:
  • COBRT043 File information missing for indexed file (Fatal)
    The most likely reason for this error is that the names of either the data part or the index part of the file are not consistent with the setting of the IDXNAMETYPE FIle Handler configuration option.
  • COBRT044 Attempt to OPEN an NLS file in a non-NLS program (Fatal)
    The logical file-name is preceded by "%NLS%", but the program which OPENS the file has been compiled without the NLS directive set: the OPEN fails.
  • COBRT045 Attempt to OPEN an NLS file using incompatible language definition (Fatal)
    The NLS control information for a file in your program does not match the same NLS control information in the header of your index file. Alternatively, your index file has become corrupted.
  • COBRT047 Indexed structure overflow (Fatal)
    The structure of your indexed file contains a fault. You have probably tried to put another entry in the index when there is no room for it. This may be because you have reached the maximum number of duplicate keys.
  • COBRT048 Attempt to divide by zero (Fatal)
    You are executing a program that is trying to perform a divide by zero.
  • COBRT055 Routine table overflow (Fatal)
    You have tried to load too many programs simultaneously.
Parent topic: Run-time System Error Messages


COBRT041 Corrupt index file (Recoverable)

Your run-time system does not recognize the control information for an indexed file and as the index has been corrupted in some way the data in the file is no longer accessible by your system. This error is recoverable in the sense that it can be trapped but should you receive it, you can do little except to close any open files and stop your program's run.

Resolution:

You should identify the cause of the error. It might be something obvious such as a crash. You can run Rebuild using the /f option to find more about the nature of the corruption.

You should rerun your program using the backup copy of that file. If you have added a great deal of information to the file since you last took a backup you might like to rebuild the file using the Rebuild utility, which reads the data (if this has not been corrupted) and builds a new index for it.

Parent topic: COBRT041 - COBRT060


COBRT042 Attempt to write on broken pipe (Recoverable)

One of the following has occurred:
  • Your program has created a process as a result of a DD_ logical file-name mapping assignment (for example, the process might be a line printer spooler). The process was not created properly, or has ended prematurely. This error occurs when your program tries to write to the process.
  • Your application has terminated abnormally or prematurely, thus breaking the pipe.

Resolution:

You can trap the error status returned by the write operation, then open the file again.

Parent topic: COBRT041 - COBRT060


COBRT043 File information missing for indexed file (Fatal)

The most likely reason for this error is that the names of either the data part or the index part of the file are not consistent with the setting of the IDXNAMETYPE FIle Handler configuration option.

Other possibilities are that you have copied the indexed file from one disk to another but have copied either only the data part of the file or only the index, or that there was a system crash during your program's previous run, while the file was open.

Resolution:

Check that the setting of the IDXNAMETYPE FIle Handler configuration option is consistent with the naming of the index files used on your system.

If the error was the result of a faulty copy you should be able to restore the missing part of the file from the .dat or .idx file.

If the error is the result of a crash then whether you can access the necessary data or not is entirely system dependent.

Parent topic: COBRT041 - COBRT060


COBRT044 Attempt to OPEN an NLS file in a non-NLS program (Fatal)

The logical file-name is preceded by "%NLS%", but the program which OPENS the file has been compiled without the NLS directive set: the OPEN fails.
Parent topic: COBRT041 - COBRT060


COBRT045 Attempt to OPEN an NLS file using incompatible language definition (Fatal)

The NLS control information for a file in your program does not match the same NLS control information in the header of your index file. Alternatively, your index file has become corrupted.

Resolution:

Rebuild your index file, or rerun your program using the backup copy of that file. If you have added a great deal of information since you last took a backup, you might want to rebuild the file using a utility that is able to read the data, if it is not corrupt, and build a new index for it.

Parent topic: COBRT041 - COBRT060


COBRT047 Indexed structure overflow (Fatal)

The structure of your indexed file contains a fault. You have probably tried to put another entry in the index when there is no room for it. This may be because you have reached the maximum number of duplicate keys.

Alternatively, you have tried to access an old format indexed file, created perhaps using CIS COBOL.

Resolution:

If your index has no room for further entries you should either reorganize your file or convert it to IDXFORMAT"4" using Rebuild, to allow a greater number of duplicate keys.

If you have tried to access an old format indexed file, you can run the Rebuild utility to check the consistency of this indexed file, and to construct a new indexed file if the old one was found to be corrupt.

Parent topic: COBRT041 - COBRT060


COBRT048 Attempt to divide by zero (Fatal)

You are executing a program that is trying to perform a divide by zero.

Resolution:

Recode your program so that you can trap the error with an ON SIZE ERROR clause

Parent topic: COBRT041 - COBRT060


COBRT055 Routine table overflow (Fatal)

You have tried to load too many programs simultaneously.

Resolution:

Cancel any programs that you are no longer using, or use fewer separate programs.

Parent topic: COBRT041 - COBRT060


COBRT061 - COBRT080

  • COBRT065 File locked (Recoverable)
    You have tried to open a file which has already been locked, or opened for output by another user. Alternatively, you have tried to lock or open for output a file which another user already has open.
  • COBRT066 Attempt to add duplicate record key to indexed file (Fatal)
    You have tried to add a duplicate key for a key which you have not defined as being able to have duplicates.
  • COBRT067 Indexed file not open (Recoverable)
    You are trying to access an indexed file which you have not opened.
  • COBRT068 Record locked (Recoverable)
    You have tried to access a record which is currently locked by another user.
  • COBRT069 Illegal argument to isam module (Fatal)
    This is the result of an internal system error.
  • COBRT070 Too many indexed files open (Recoverable)
    You are trying to open an indexed file but you have already exhausted the system limit which specifies how many of these files can be opened at any one time.
  • COBRT071 Bad indexed file format (Fatal)
    You are either using a file which has been corrupted, or there is an internal system error.
  • COBRT072 End of indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT073 No record found in indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT074 No current record in indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT075 Indexed data file name too long (Fatal)
    When creating indexed files, the extension .idx is added to the user-defined filename, so your filename must not exceed x-4 characters in length, where x is the maximum length of filename.
  • COBRT076 Can't create lock file in /isam directory (Fatal)
    For some reason your system is unable to create a lock file in the /isam directory. One reason for this could be that in its previous run your program terminated abnormally (perhaps due to a power failure) leaving some files locked.
  • COBRT077 Internal ISAM module error (Fatal)
    This is the result of an internal system error.
  • COBRT078 Illegal key description in indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT079 COBCONFIG syntax error (Fatal)
    An error exists in the run-time configuration file accessed via the environment variable COBCONFIG.
  • COBRT080 Can't convert to/from Unicode codeset (Fatal)
    You have tried to use the additional language variants but there are no mapping tables to convert to/from one of the codesets.
Parent topic: Run-time System Error Messages


COBRT065 File locked (Recoverable)

You have tried to open a file which has already been locked, or opened for output by another user. Alternatively, you have tried to lock or open for output a file which another user already has open.

Resolution:

Your program can inform the system operator (if there is one) that it is unable to access this file and should wait until the other user has finished using the file and closes it. You should then be able to continue to run your program.

Parent topic: COBRT061 - COBRT080


COBRT066 Attempt to add duplicate record key to indexed file (Fatal)

You have tried to add a duplicate key for a key which you have not defined as being able to have duplicates.

Resolution:

As this error implies that your program logic contains a mistake, you probably should recode.

Parent topic: COBRT061 - COBRT080


COBRT067 Indexed file not open (Recoverable)

You are trying to access an indexed file which you have not opened.

Resolution:

Open the file in the relevant access mode and then retry the unsuccessful file operation.

Parent topic: COBRT061 - COBRT080


COBRT068 Record locked (Recoverable)

You have tried to access a record which is currently locked by another user.

Resolution:

Your program can inform the system operator (if there is one) that the record is currently locked, and you should then wait until the other user has released the lock on that record. You should then be able to access the relevant record. You should not continually retry to gain access to the record without operator intervention, as this could result in your application hanging.

Parent topic: COBRT061 - COBRT080


COBRT069 Illegal argument to isam module (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT070 Too many indexed files open (Recoverable)

You are trying to open an indexed file but you have already exhausted the system limit which specifies how many of these files can be opened at any one time.

Resolution:

Close some of the open indexed files which you are not currently accessing. You should then be able to open the indexed file which you require and to continue the program run.

Parent topic: COBRT061 - COBRT080


COBRT071 Bad indexed file format (Fatal)

You are either using a file which has been corrupted, or there is an internal system error.

Resolution:

If the disk you are using is corrupt, rerun your program using your backup copy of the disk. If this is not the cause of the error then you should contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT072 End of indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT073 No record found in indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of the error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT074 No current record in indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of the error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT075 Indexed data file name too long (Fatal)

When creating indexed files, the extension .idx is added to the user-defined filename, so your filename must not exceed x-4 characters in length, where x is the maximum length of filename.

Resolution:

Rename the file with a shorter filename, that is, one that is less than 10 characters in length.

Parent topic: COBRT061 - COBRT080


COBRT076 Can't create lock file in /isam directory (Fatal)

For some reason your system is unable to create a lock file in the /isam directory. One reason for this could be that in its previous run your program terminated abnormally (perhaps due to a power failure) leaving some files locked.

Resolution:

You should manually remove all of the files that are still locked from the /isam directory before you can successfully run your program.

Parent topic: COBRT061 - COBRT080


COBRT077 Internal ISAM module error (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT078 Illegal key description in indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT061 - COBRT080


COBRT079 COBCONFIG syntax error (Fatal)

An error exists in the run-time configuration file accessed via the environment variable COBCONFIG.

Resolution:

Check the syntax of the entries in the configuration file. You might have used incorrect syntax, or syntax that is not compatible with the type of run-time tunable you are configuring (this could include assigning an illegal value to the tunable).

Parent topic: COBRT061 - COBRT080


COBRT080 Can't convert to/from Unicode codeset (Fatal)

You have tried to use the additional language variants but there are no mapping tables to convert to/from one of the codesets.

Resolution:

Check that the operating system Unicode mapping tables have been installed on your machine. If converting to/from the current locale, ensure that operating system mapping tables exist for the corresponding codeset.

Parent topic: COBRT061 - COBRT080


COBRT101 - COBRT120

  • COBRT081 Key already exists in indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT082 CALL convention not supported (Fatal)
    The CALL convention you have specified is not supported.
  • COBRT086 Remote file system failure (Fatal)
  • COBRT099 Illegal operation in SORT/MERGE module (Fatal)
    A SORT or MERGE module has received a RELEASE operation outside the Input procedure, or a RETURN operation either outside the Output procedure, or before the Input procedure has terminated correctly.
  • COBRT100 Invalid file operation (Fatal)
    You have tried a file operation which violates a general rule of COBOL in some way. The most likely cause of this error is that you have tried a rewrite on a sequential file opened I-O, or on a relative file with access mode sequential also opened I-O, without preceding it with a successful read NEXT.
  • COBRT101 Illegal operation on an indexed file (Fatal)
    This is the result of an internal system error.
  • COBRT102 Sequential file with non-integral number of records (Fatal)
    You have either specified an incorrect record length for a sequential file, or the sequential file you are trying to access is corrupt in some way, or the file which you have specified is not a sequential file.
  • COBRT103 Parameter cannot be passed BY VALUE (Fatal)
  • COBRT104 Null file name used in a file operation (Fatal)
    You specified a data-name for a file-name instead of a literal, and the data item contained only spaces when you tried to open the file.
  • COBRT105 Memory allocation error (Fatal)
    The run-time system is unable to allocate sufficient memory space to successfully carry out the tried operation, probably because of insufficient memory space on your system.
  • COBRT106 Dictionary error (Fatal)
    This could be the result of a read or write error to file or disk, but it is more likely to be the result of an internal system error.
  • COBRT107 Operation not implemented in this run-time system (Fatal)
    You are trying to perform a file operation which your run-time system does not support.
  • COBRT108 Failure to initialize data division (Fatal)
    The run-time system cannot load your program properly because the data needed to correctly initialize the Data Division has become corrupted.
  • COBRT109 Invalid checksum in run-time system (Recoverable)
    The internal information in the run-time system has been altered. The run-time system might have become corrupted, or you might have illegally tried to change the internal run-time system information.
  • COBRT110 Generated code not supported by this RTS (Fatal)
  • COBRT111 Incompatible Class Library and Run-Time Environment versions (Fatal)
    The version numbers for these components do not match.
  • COBRT112 Unable to locate/access the required security key (Recoverable)
    The run-time system cannot locate or cannot access the coded security key (dongle) that is required to execute this application.
  • COBRT114 Attempt to access item beyond bounds of memory (Fatal)
    Memory access violation has been detected by your operating system.
  • COBRT115 Unexpected signal (Fatal)
    A signal the run-time system was not expecting has been caught.
  • COBRT116 Cannot allocate memory (Fatal)
    For some reason a part of your run-time system is unable to allocate you sufficient memory to enable you to execute your code.
  • COBRT117 Bad collating sequence (Fatal)
    This is an internal system error.
  • COBRT118 Symbol not found (Fatal)
    You have attempted to reference a name that has not been defined.
  • COBRT119 Symbol redefined (Fatal)
    The run-time system has detected a symbol (for example, data item, entry point or module name) which is already defined.
  • COBRT120 Symbol string table of zero size (Fatal)
    You probably have a malformed object file.
Parent topic: Run-time System Error Messages


COBRT081 Key already exists in indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT101 - COBRT120


COBRT082 CALL convention not supported (Fatal)

The CALL convention you have specified is not supported.

Resolution:

Change the convention defined in the Special-Names paragraph to one of the supported CALL conventions.

Parent topic: COBRT101 - COBRT120


COBRT086 Remote file system failure (Fatal)

Parent topic: COBRT101 - COBRT120


COBRT099 Illegal operation in SORT/MERGE module (Fatal)

A SORT or MERGE module has received a RELEASE operation outside the Input procedure, or a RETURN operation either outside the Output procedure, or before the Input procedure has terminated correctly.

Resolution:

Recode your program so that RELEASE and RETURN operations are issued by the appropriate procedures.

Parent topic: COBRT101 - COBRT120


COBRT100 Invalid file operation (Fatal)

You have tried a file operation which violates a general rule of COBOL in some way. The most likely cause of this error is that you have tried a rewrite on a sequential file opened I-O, or on a relative file with access mode sequential also opened I-O, without preceding it with a successful read NEXT.

Resolution:

Recode your program to ensure that the REWRITE statement in error is preceded by a read NEXT.

Parent topic: COBRT101 - COBRT120


COBRT101 Illegal operation on an indexed file (Fatal)

This is the result of an internal system error.

Resolution:

Contact Technical Support who will help you discover the cause of your error and how it can be rectified.

Parent topic: COBRT101 - COBRT120


COBRT102 Sequential file with non-integral number of records (Fatal)

You have either specified an incorrect record length for a sequential file, or the sequential file you are trying to access is corrupt in some way, or the file which you have specified is not a sequential file.

Resolution:

Recode your program so that it specifies the correct type of file, or if the error is the result of a corrupt file, try to run the program again using a backup copy of that file.

Parent topic: COBRT101 - COBRT120


COBRT103 Parameter cannot be passed BY VALUE (Fatal)

Parent topic: COBRT101 - COBRT120


COBRT104 Null file name used in a file operation (Fatal)

You specified a data-name for a file-name instead of a literal, and the data item contained only spaces when you tried to open the file.

Alternatively, you have attempted to do a CALL dataname in which the dataname has at least one leading space character.

Resolution:

Recode your program specifying the correct file-name.

Ensure the target program name is space terminated.

Parent topic: COBRT101 - COBRT120


COBRT105 Memory allocation error (Fatal)

The run-time system is unable to allocate sufficient memory space to successfully carry out the tried operation, probably because of insufficient memory space on your system.

Resolution:

You should obtain more memory in which to run your program. Refer to your operating system documentation for details of how you can obtain more memory, if this is possible.

Parent topic: COBRT101 - COBRT120


COBRT106 Dictionary error (Fatal)

This could be the result of a read or write error to file or disk, but it is more likely to be the result of an internal system error.

Alternatively, your application might have called many programs without canceling them afterward, so that memory becomes exhausted during animation.

Resolution:

Contact Technical Support who will help you to discover the cause of your error and how it can be rectified.

Ensure that as much memory as possible is available during animation by CANCELing any program you do not currently need to access.

Parent topic: COBRT101 - COBRT120


COBRT107 Operation not implemented in this run-time system (Fatal)

You are trying to perform a file operation which your run-time system does not support.

Resolution:

You should recode your program so that it does not try such operations, or you should acquire a version of your system that does support this facility.

Parent topic: COBRT101 - COBRT120


COBRT108 Failure to initialize data division (Fatal)

The run-time system cannot load your program properly because the data needed to correctly initialize the Data Division has become corrupted.

Resolution:

You should compile your program again to try to obtain good intermediate code.

Parent topic: COBRT101 - COBRT120


COBRT109 Invalid checksum in run-time system (Recoverable)

The internal information in the run-time system has been altered. The run-time system might have become corrupted, or you might have illegally tried to change the internal run-time system information.

The internal information in the run-time system has been altered. The run-time system might have become corrupted, or you might have illegally tried to change the internal run-time system information.

Parent topic: COBRT101 - COBRT120


COBRT110 Generated code not supported by this RTS (Fatal)

Resolution:

Contact Technical Support who will help you to discover the cause of the error and how it can be rectified.

Parent topic: COBRT101 - COBRT120


COBRT111 Incompatible Class Library and Run-Time Environment versions (Fatal)

The version numbers for these components do not match.

Resolution:

Check that you have fully installed both the Class Library and the Run-Time Environment from the same version of your COBOL system. If you have more than one version installed, check that your PATH and COBDIR environment variables specify an appropriate path for the version you are using.

Parent topic: COBRT101 - COBRT120


COBRT112 Unable to locate/access the required security key (Recoverable)

The run-time system cannot locate or cannot access the coded security key (dongle) that is required to execute this application.

Resolution:

Connect the security key that was supplied with your COBOL system to the parallel port of your computer, then re-run the application.

Parent topic: COBRT101 - COBRT120


COBRT114 Attempt to access item beyond bounds of memory (Fatal)

Memory access violation has been detected by your operating system.

The file mfdebug.log is automatically generated in your current directory.

Parent topic: COBRT101 - COBRT120


COBRT115 Unexpected signal (Fatal)

A signal the run-time system was not expecting has been caught.

If you are running under Windows, the file mfdebug.log is automatically generated in your current directory.

Parent topic: COBRT101 - COBRT120


COBRT116 Cannot allocate memory (Fatal)

For some reason a part of your run-time system is unable to allocate you sufficient memory to enable you to execute your code.

Resolution:

You should try to reduce memory usage by canceling programs that are not in use, then try the operation that caused this message again.

Parent topic: COBRT101 - COBRT120


COBRT117 Bad collating sequence (Fatal)

This is an internal system error.

Resolution:

Contact Technical Support who will help you to discover the cause of the error and how it can be rectified.

Parent topic: COBRT101 - COBRT120


COBRT118 Symbol not found (Fatal)

You have attempted to reference a name that has not been defined.
Parent topic: COBRT101 - COBRT120


COBRT119 Symbol redefined (Fatal)

The run-time system has detected a symbol (for example, data item, entry point or module name) which is already defined.

OO programs can also cause this error for either of the following reasons:

  • You have defined the same method-name twice in a single object
  • You have defined the same class name with different filenames in different programs, in the Class-Control paragraph. Filename matching is case-sensitive; class filenames should always be coded in lower-case.

Resolution:

You can recode your application to remove the naming duplication.

Parent topic: COBRT101 - COBRT120


COBRT120 Symbol string table of zero size (Fatal)

You probably have a malformed object file.

Resolution:

Once the program has terminated you must correct your object file. If this does not work, contact Technical Support who will help you to discover the specific cause of the error.

Parent topic: COBRT101 - COBRT120


COBRT121 - COBRT140

  • COBRT121 Symbol is not in TEXT section (Fatal)
    You have tried to call a subprogram that is not an executable program.
  • COBRT122 Coblongjmp() called below level of cobsavenv() (Fatal)
    You might have returned control to a higher level in the CALL/PERFORM hierarchy than the level at which cobsetjmp was called. Coblongjmp must be called only from the same or from a lower level in the CALL/PERFORM hierarchy as cobsavenv was.
  • COBRT123 Unknown relocation type (Fatal)
    You are using incompatible versions of the object file and the COBOL run-time library.
  • COBRT124 Communication failure during I/O request to the central file handler
  • COBRT125 All locks/ current transactions canceled due to exceeding time limit
  • COBRT126 Record size exceeds system limit (Fatal)
    One of the following has occurred:
  • COBRT127 coblongjmp() called from a different thread to cobsetjmp() (Fatal)
    You have called coblongjmp() in a different thread from the corresponding call to cobsetjmp(). coblongjmp() must be called from the same thread as the corresponding call to cobsetjmp().
  • COBRT129 Attempt to access record zero of relative file (Recoverable)
    The value specified in the RELATIVE KEY data item contains the value zero.
  • COBRT135 File not found (Recoverable)
    The operating system has been unable to find a file which you have tried to access in your program.
  • COBRT136 Corrupt or invalid executable file (Fatal)
    An attempt was made to execute a .gnt file or a library file that is not valid. The file might be corrupted or truncated.
  • COBRT137 Illegal device specification - not mass storage
  • COBRT138 File closed with lock - cannot be opened (Recoverable)
    You are trying to open a file which you previously closed with lock, which violates one of the general rules of COBOL programming.
  • COBRT139 Record length or key data inconsistency (Recoverable)
    A discrepancy exists between the length of a record, or the keys which you have specified, in your current program and its definition in the program in which it was first opened.
Parent topic: Run-time System Error Messages


COBRT121 Symbol is not in TEXT section (Fatal)

You have tried to call a subprogram that is not an executable program.

Alternatively, you have used the same name for a called program as for a previously defined data item.

Resolution:

Check that the subprogram being called is an executable one. If required, correct the subprogram's name in the calling program and resubmit it to your COBOL system.

Once your program has terminated, recode it to remove the naming duplication. Resubmit your program to your COBOL system.

Parent topic: COBRT121 - COBRT140


COBRT122 Coblongjmp() called below level of cobsavenv() (Fatal)

You might have returned control to a higher level in the CALL/PERFORM hierarchy than the level at which cobsetjmp was called. Coblongjmp must be called only from the same or from a lower level in the CALL/PERFORM hierarchy as cobsavenv was.

Resolution:

Check and correct the logic of your program, and then resubmit your program to your COBOL system.

Parent topic: COBRT121 - COBRT140


COBRT123 Unknown relocation type (Fatal)

You are using incompatible versions of the object file and the COBOL run-time library.

Resolution:

Once the program has terminated, resubmit your object file to your COBOL system with the current version of your COBOL run-time library. If this does not work, contact Technical Support who will help you to discover the specific cause of the error.

Parent topic: COBRT121 - COBRT140


COBRT124 Communication failure during I/O request to the central file handler

Parent topic: COBRT121 - COBRT140


COBRT125 All locks/ current transactions canceled due to exceeding time limit

Parent topic: COBRT121 - COBRT140


COBRT126 Record size exceeds system limit (Fatal)

One of the following has occurred:
  • You have attempted to open for output a file whose record length is greater than the system limits. For C-ISAM format files, the limit is 32,767 bytes. For Micro Focus format files, the limit is 268,433,408 bytes.
  • You have attempted a REWRITE on a sequential file using data compression where the compressed length of the new record differs from that of the original.

Resolution:

Correct the record size.

Parent topic: COBRT121 - COBRT140


COBRT127 coblongjmp() called from a different thread to cobsetjmp() (Fatal)

You have called coblongjmp() in a different thread from the corresponding call to cobsetjmp(). coblongjmp() must be called from the same thread as the corresponding call to cobsetjmp().

Resolution:

Check and correct the logic of your program, then resubmit it to your COBOL system.

Parent topic: COBRT121 - COBRT140


COBRT129 Attempt to access record zero of relative file (Recoverable)

The value specified in the RELATIVE KEY data item contains the value zero.

Resolution:

You should ensure that the value in the RELATIVE KEY data item is greater than zero, then continue to run your program.

Parent topic: COBRT121 - COBRT140


COBRT135 File not found (Recoverable)

The operating system has been unable to find a file which you have tried to access in your program.

Resolution:

Ensure that you are in the correct directory or that a path to the file concerned exists. You can then try the file operation again. If the error is the result of a spelling mistake then ask for the correct file and try the file operation again.

Parent topic: COBRT121 - COBRT140


COBRT136 Corrupt or invalid executable file (Fatal)

An attempt was made to execute a .gnt file or a library file that is not valid. The file might be corrupted or truncated.

Resolution:

Recompile the source code or recreate the library file, ensuring that it is processed without errors.

Parent topic: COBRT121 - COBRT140


COBRT137 Illegal device specification - not mass storage

Parent topic: COBRT121 - COBRT140


COBRT138 File closed with lock - cannot be opened (Recoverable)

You are trying to open a file which you previously closed with lock, which violates one of the general rules of COBOL programming.

Resolution:

You cannot open the relevant file. As this error implies that your program logic contains a mistake, you might want to close any remaining open files, execute a STOP RUN statement and recode.

Parent topic: COBRT121 - COBRT140


COBRT139 Record length or key data inconsistency (Recoverable)

A discrepancy exists between the length of a record, or the keys which you have specified, in your current program and its definition in the program in which it was first opened.

Resolution:

Your program has a fault, so you probably should edit your code, then resubmit it to your COBOL system before running it again.

Parent topic: COBRT121 - COBRT140


COBRT141 - COBRT160

  • COBRT141 File already open - cannot be opened (Recoverable)
    You have tried to open a file which is already open and so cannot be opened again.
  • COBRT142 File not open - cannot be closed (Recoverable)
    You have tried to close a file which is not open which is impossible to achieve.
  • COBRT143 Rewrite/delete in sequential mode not preceded by successful read (Recoverable)
    You have failed to do a successful read on a sequentially accessed file trying a REWRITE or DELETE on some of the information contained in that file.
  • COBRT144 Boundary violation (Recoverable)
    You have tried to write a record to a variable length record file, the length of which is not within the defined range for that file.
  • COBRT146 No current record defined for sequential read (Recoverable)
    The file position indicator in your file is undefined owing to a failed read/START or INVALID KEY condition. You have tried to read another record in the file but as the current record is undefined the system cannot find the start of the record for which you have asked.
  • COBRT147 Wrong open mode or access mode for read/start (Recoverable)
    You have tried to carry out a read or START operation on a file which has not been opened for INPUT or I-O, or which is not open at all.
  • COBRT148 Wrong open mode or access mode for write (Recoverable)
    You have tried to write to a file in sequential access mode that you have not opened for OUTPUT or EXTEND, or you have tried to write to a file in random or dynamic access mode that has not been opened INPUT or I-O, or which is not open at all.
  • COBRT149 Wrong open mode or access mode for rewrite/delete (Recoverable)
    You are trying to do a REWRITE or a DELETE on a file that you have not opened for I-O, or which is not open at all.
  • COBRT151 Random read on sequential file (Recoverable)
    You are trying to do a random read on a file which has sequential organization.
  • COBRT152 REWRITE on file not opened I-O (Recoverable)
    You have tried a REWRITE on a file that is not open I-O.
  • COBRT153 Subscript out of range (Fatal)
    A subscript which you have used in your program is out of the defined range, that is, it is either less than one or it is greater than the number of occurrences of the item.
  • COBRT154 PERFORM nested too deeply (Fatal)
    This error usually results if you have used GO TO to jump out of the range of a PERFORM rather than to jump to an EXIT statement at the end of its range.
  • COBRT155 Illegal command line (Fatal)
    The run-time system does not recognize as valid the command line format you have specified.
  • COBRT156 Too many parentheses in compute statement (Fatal)
    You have coded a COMPUTE statement which is too complex for your system to handle successfully.
  • COBRT157 Not enough program memory: object file too large to load (Recoverable)
    Either your program is too large for the available memory space, or the stack is full.
  • COBRT158 Attempt to REWRITE to a line-sequential file (Recoverable)
    You have used the REWRITE statement in conjunction with a file whose organization is line sequential. The REWRITE statement cannot be used with line sequential files.
  • COBRT159 Malformed line-sequential file (Recoverable)
    A line-sequential file which you are trying to access is corrupt in some way.
  • COBRT160 Overlay loading error (Recoverable)
    An error has occurred while trying to load the intermediate code for an independent segment. The segment is either missing or corrupted in some way.
Parent topic: Run-time System Error Messages


COBRT141 File already open - cannot be opened (Recoverable)

You have tried to open a file which is already open and so cannot be opened again.

Resolution:

Cancel your second attempt to open the file and continue to run your program if the fact that the file is already open is acceptable to you. However as this error implies that your program logic contains a mistake, you might want to close any open files, execute a STOP RUN statement and then recode.

Parent topic: COBRT141 - COBRT160


COBRT142 File not open - cannot be closed (Recoverable)

You have tried to close a file which is not open which is impossible to achieve.

Resolution:

You can abandon your attempt to close the relevant file and continue to run your program. However, as this error implies that your program logic contains a mistake, you might want to close any open files, execute a STOP RUN statement and then recode.

Parent topic: COBRT141 - COBRT160


COBRT143 Rewrite/delete in sequential mode not preceded by successful read (Recoverable)

You have failed to do a successful read on a sequentially accessed file trying a REWRITE or DELETE on some of the information contained in that file.

Resolution:

If the previous read was successful then perform a read on the relevant file before you retry the unsuccessful REWRITE or DELETE operation. If the previous read was also unsuccessful close the file, execute a STOP RUN statement and then recode your program before you next run it.

Parent topic: COBRT141 - COBRT160


COBRT144 Boundary violation (Recoverable)

You have tried to write a record to a variable length record file, the length of which is not within the defined range for that file.

Resolution:

Recode your program.

Parent topic: COBRT141 - COBRT160


COBRT146 No current record defined for sequential read (Recoverable)

The file position indicator in your file is undefined owing to a failed read/START or INVALID KEY condition. You have tried to read another record in the file but as the current record is undefined the system cannot find the start of the record for which you have asked.

Resolution:

You should try a START operation, and continue to do so until the file position indicator is updated successfully.

Parent topic: COBRT141 - COBRT160


COBRT147 Wrong open mode or access mode for read/start (Recoverable)

You have tried to carry out a read or START operation on a file which has not been opened for INPUT or I-O, or which is not open at all.

Resolution:

Open the file for I-O or for INPUT and you should then be able to continue to run your program. However, as this error implies that your program logic contains a mistake, you might want to close any files which are open, execute a STOP RUN statement and then recode.

Parent topic: COBRT141 - COBRT160


COBRT148 Wrong open mode or access mode for write (Recoverable)

You have tried to write to a file in sequential access mode that you have not opened for OUTPUT or EXTEND, or you have tried to write to a file in random or dynamic access mode that has not been opened INPUT or I-O, or which is not open at all.

Resolution:

Close the file and reopen it with the correct open mode for the file type. However, as this error implies that your program logic contains a mistake, you might want to close any files that are open, execute a STOP RUN statement and then recode.

Parent topic: COBRT141 - COBRT160


COBRT149 Wrong open mode or access mode for rewrite/delete (Recoverable)

You are trying to do a REWRITE or a DELETE on a file that you have not opened for I-O, or which is not open at all.

Resolution:

Close the file and reopen for I-O. However, as this error implies that your program logic contains a mistake, you might want to close any open files, execute a STOP RUN statement and then recode.

Parent topic: COBRT141 - COBRT160


COBRT151 Random read on sequential file (Recoverable)

You are trying to do a random read on a file which has sequential organization.

Resolution:

Read the file with the correct access mode. As this error implies that your program logic contains a mistake, you might like to close any files which are open, execute a STOP RUN statement and recode.

Parent topic: COBRT141 - COBRT160


COBRT152 REWRITE on file not opened I-O (Recoverable)

You have tried a REWRITE on a file that is not open I-O.

Resolution:

Close the relevant file and open it for I-O operations. You should then be able to carry out the REWRITE operation successfully. However, as this error implies that your program logic contains a mistake, you might want to close any open files, execute a STOP RUN statement and then recode.

Parent topic: COBRT141 - COBRT160


COBRT153 Subscript out of range (Fatal)

A subscript which you have used in your program is out of the defined range, that is, it is either less than one or it is greater than the number of occurrences of the item.

Resolution:

You should recode your program.

Parent topic: COBRT141 - COBRT160


COBRT154 PERFORM nested too deeply (Fatal)

This error usually results if you have used GO TO to jump out of the range of a PERFORM rather than to jump to an EXIT statement at the end of its range.

Resolution:

When your program has terminated you should to recode your program to ensure that the GO TO in question jumps to an EXIT statement at the end of the PERFORM's range.

Parent topic: COBRT141 - COBRT160


COBRT155 Illegal command line (Fatal)

The run-time system does not recognize as valid the command line format you have specified.

Alternatively, the generic command-line interpreter, which must be present if your program is to be run successfully, is not found on your system.

Alternatively, you have set an invalid COBSW value.

Resolution:

Rerun your application with a valid command line.

Make sure that the interpreter is present to enable your system to pick up the commands correctly and then rerun your program.

Reset COBSW to a valid value.

Parent topic: COBRT141 - COBRT160


COBRT156 Too many parentheses in compute statement (Fatal)

You have coded a COMPUTE statement which is too complex for your system to handle successfully.

Resolution:

You should recode your program. We strongly advise you to break the relevant COMPUTE statement into a number of simpler statements.

Parent topic: COBRT141 - COBRT160


COBRT157 Not enough program memory: object file too large to load (Recoverable)

Either your program is too large for the available memory space, or the stack is full.

Resolution:

If you have specified the ON OVERFLOW/EXCEPTION clause in the relevant CALL statement, the error is recoverable. Any associated imperative statement is executed before the next instruction.

Parent topic: COBRT141 - COBRT160


COBRT158 Attempt to REWRITE to a line-sequential file (Recoverable)

You have used the REWRITE statement in conjunction with a file whose organization is line sequential. The REWRITE statement cannot be used with line sequential files.

Resolution:

Close the file in error before executing a STOP RUN statement to ensure that you do not lose any data from it. Recode your program to make the organization of the file to which you want to do a REWRITE either sequential, indexed sequential, or relative.

Parent topic: COBRT141 - COBRT160


COBRT159 Malformed line-sequential file (Recoverable)

A line-sequential file which you are trying to access is corrupt in some way.

Resolution:

Rerun your program using the backup copy of that file.

Parent topic: COBRT141 - COBRT160


COBRT160 Overlay loading error (Recoverable)

An error has occurred while trying to load the intermediate code for an independent segment. The segment is either missing or corrupted in some way.

Resolution:

If the segment is missing, locate it. If you cannot find it, or if it is present and corrupt, resubmit your program to your COBOL system.

Parent topic: COBRT141 - COBRT160


COBRT161 - COBRT180

  • COBRT161 Illegal intermediate code (Fatal)
    The intermediate code which is currently being processed is not valid code. You are probably trying to execute a corrupted file or one which has not been submitted to your COBOL system successfully.
  • COBRT162 Arithmetic overflow or underflow (Fatal)
    You are executing a program that is trying to perform a floating-point divide by zero.
  • COBRT163 Illegal character in numeric field (Fatal)
    The contents of a numeric or numeric edited field are inconsistent with the picture definition of that field.
  • COBRT164 Run-Time subprogram not found (Fatal)
    You have tried to call a subroutine whose entry address has not been set up in your run-time system.
  • COBRT165 Version number incompatibility (Fatal)
    You have tried to:
  • COBRT166 Recursive COBOL CALL is illegal (Fatal)
    You have tried to call a COBOL module that is already active.
  • COBRT167 Too many USING items (Fatal)
    The list of items which you have supplied in a CALL....USING statement is longer than the run-time system can handle.
  • COBRT168 Stack overflow (Fatal)
    You have nested a PERFORM statement or a series of CALL statements too deeply.
  • COBRT169 Illegal configuration information (Fatal)
    You have tried an operation for which your machine is not configured; the most likely cause of this is that Adis is not configured correctly.
  • COBRT170 System program not found (Fatal)
    A system program, for example Adis or Mffh, is not present.
  • COBRT171 Japanese operations illegal with this RTS (Fatal)
    You are trying to perform Japanese operations with a non-Japanese run-time system, or you have used a Japanese version of your COBOL system to produce code which you are now trying to run using a non-Japanese run-time system.
  • COBRT173 Called program file not found in drive/directory (Fatal)
    You have tried to call a program which is not present on your current logged-in drive or directory, or in a directory pointed to by the COBDIR environment variable, or to send a message to a class which cannot be loaded.
  • COBRT174 Imported file not found (Fatal)
    You have tried to load a .dll file which contains references to another .dll file which cannot be found by the operating system.
  • COBRT175 Attempt to run intermediate code program which had severe errors in it (Fatal)
    You are trying to run a program that produced severe faults when you submitted it to your COBOL system with the run-time switch E turned off.
  • COBRT176 Illegal intersegment reference (Fatal)
    You might have a corrupted file. Alternatively, your code contains a segment reference for the Forward Reference Table which is illegal.
  • COBRT177 Attempt to cancel program failed (Fatal)
    You have tried to remove a currently executing program or its parents or grandparents, from memory.
  • COBRT179 Error during chain (program not found) (Fatal)
    You have tried to chain to another program which your system is unable to find.
  • COBRT180 End-of-file marker error (Fatal)
    A file-marker used to indicate that the end-of-file has been reached is missing from one of your files.
Parent topic: Run-time System Error Messages


COBRT161 Illegal intermediate code (Fatal)

The intermediate code which is currently being processed is not valid code. You are probably trying to execute a corrupted file or one which has not been submitted to your COBOL system successfully.

Resolution:

You should resubmit your source program to your COBOL system, to try to obtain uncorrupted intermediate code.

or:

If your application is invoking the File Handler directly using calls to EXTFH or mFFH, you might encounter this error if the key definition block has been incorrectly defined. Please refer to the File Handler reference documentation for details about the correct format of the key definition block.

Parent topic: COBRT161 - COBRT180


COBRT162 Arithmetic overflow or underflow (Fatal)

You are executing a program that is trying to perform a floating-point divide by zero.

Resolution:

You should recode your program to avoid this illegal operation.

Parent topic: COBRT161 - COBRT180


COBRT163 Illegal character in numeric field (Fatal)

The contents of a numeric or numeric edited field are inconsistent with the picture definition of that field.

Resolution:

Adjust your code so that no invalid data is used, or set the –F run-time switch to suppress the checking of numeric items for valid data.

Parent topic: COBRT161 - COBRT180


COBRT164 Run-Time subprogram not found (Fatal)

You have tried to call a subroutine whose entry address has not been set up in your run-time system.

Resolution:

Check to see that you used a valid call number in the unsuccessful subroutine call. If not, revise your code to contain a call number which your system recognizes. If you did use a valid call number but still received this error you should contact Technical Support.

Parent topic: COBRT161 - COBRT180


COBRT165 Version number incompatibility (Fatal)

You have tried to:
  • Run a program that has:intermediate code which has been produced on a version of your COBOL system that is incompatible with the run-time system you are using. Your run-time system, therefore, cannot execute correctly any generated code you are producing or have already produced from this intermediate code.
  • Execute a file which is not in your COBOL system's intermediate or generated code.
  • Load a module whose format is not valid for the Win32 platform.
Parent topic: COBRT161 - COBRT180


COBRT166 Recursive COBOL CALL is illegal (Fatal)

You have tried to call a COBOL module that is already active.

Resolution:

You should recode your program.

Parent topic: COBRT161 - COBRT180


COBRT167 Too many USING items (Fatal)

The list of items which you have supplied in a CALL....USING statement is longer than the run-time system can handle.

Resolution:

Once your program has terminated recode it with group items rather than elementary items before rerunning it.

Parent topic: COBRT161 - COBRT180


COBRT168 Stack overflow (Fatal)

You have nested a PERFORM statement or a series of CALL statements too deeply.

Resolution:

Edit your program to reduce the number of levels in the nested PERFORM or CALL statement.

Parent topic: COBRT161 - COBRT180


COBRT169 Illegal configuration information (Fatal)

You have tried an operation for which your machine is not configured; the most likely cause of this is that Adis is not configured correctly.

Resolution:

Check that Adis is configured correctly.

Parent topic: COBRT161 - COBRT180


COBRT170 System program not found (Fatal)

A system program, for example Adis or Mffh, is not present.

Resolution:

Ensure that all the system programs are available and copy those which are not currently present using. Once all the necessary system programs are available you can run your program.

Parent topic: COBRT161 - COBRT180


COBRT171 Japanese operations illegal with this RTS (Fatal)

You are trying to perform Japanese operations with a non-Japanese run-time system, or you have used a Japanese version of your COBOL system to produce code which you are now trying to run using a non-Japanese run-time system.

Resolution:

You should resubmit your program using a non-Japanese run-time system, or if you still want your program to perform Japanese operations, you should acquire a Japanese run-time system.

Parent topic: COBRT161 - COBRT180


COBRT173 Called program file not found in drive/directory (Fatal)

You have tried to call a program which is not present on your current logged-in drive or directory, or in a directory pointed to by the COBDIR environment variable, or to send a message to a class which cannot be loaded.

Resolution:

Once your program has terminated you should copy the relevant file into your logged-in drive or directory. If insufficient space is available, you should set the COBDIR environment variable to search the directory or drive on which the file is present when your program calls it.

If the error was caused by a class which could not be loaded, find out whether or not the filename for the class (listed in the Class-Control paragraph) is a separate executable file, or contained in a .dll or .lbr file. If it is a separate executable file, the resolution is as above. If it is part of a .dll or .lbr file, ensure that the containing file has been loaded with a CALL statement before sending messages to any of the classes. If the program not found is P2emgr, you need to load the GUI Class Library, with a CALL "APIGUI" statement.

Parent topic: COBRT161 - COBRT180


COBRT174 Imported file not found (Fatal)

You have tried to load a .dll file which contains references to another .dll file which cannot be found by the operating system.

Resolution:

Locate the missing file and ensure it is located on the default search path for your operating system.

Parent topic: COBRT161 - COBRT180


COBRT175 Attempt to run intermediate code program which had severe errors in it (Fatal)

You are trying to run a program that produced severe faults when you submitted it to your COBOL system with the run-time switch E turned off.

Alternatively, you could try to run the program with the E run-time switch set, though this might not give the desired results.

Resolution:

You should edit your source code to correct all the severe faults, resubmit it to your COBOL system, then run the intermediate code that is produced.

When your program is being animated, the debugger reports this error and enables you to continue to run the program.

Parent topic: COBRT161 - COBRT180


COBRT176 Illegal intersegment reference (Fatal)

You might have a corrupted file. Alternatively, your code contains a segment reference for the Forward Reference Table which is illegal.

Resolution:

Resubmit your source code to your COBOL system. If you receive this error again, contact Technical Support who will help you to discover the specific cause of the error.

Parent topic: COBRT161 - COBRT180


COBRT177 Attempt to cancel program failed (Fatal)

You have tried to remove a currently executing program or its parents or grandparents, from memory.

Resolution:

Once your program has terminated you need to recode your program to ensure that you do not try to cancel a program (or its parents or grandparents) while it is still being executed.

Parent topic: COBRT161 - COBRT180


COBRT179 Error during chain (program not found) (Fatal)

You have tried to chain to another program which your system is unable to find.

Resolution:

Once your program has terminated you should copy the relevant file into your logged-in drive or directory. If insufficient space is available, you should set the COBDIR environment variable to include the directory or drive on which the file is present when your program calls it.

Parent topic: COBRT161 - COBRT180


COBRT180 End-of-file marker error (Fatal)

A file-marker used to indicate that the end-of-file has been reached is missing from one of your files.

Resolution:

You should resubmit your code to your COBOL system, or use a debugger to place the end-of-file marker at the end of the file. You can then rerun your program.

Parent topic: COBRT161 - COBRT180


COBRT181 - COBRT200

  • COBRT181 Invalid parameter error (Fatal)
    A parameter which you have used is not one which is recognized by your system.
  • COBRT182 Console input or console output open in wrong direction (Fatal)
    You are either trying to read input from the screen or write to the keyboard.
  • COBRT183 Attempt to open line sequential file for I-O (Fatal)
    You have tried to open a line-sequential file in the input-output open mode, but this mode is not supported for files with this organization.
  • COBRT184 ACCEPT/DISPLAY I-O error (Fatal)
    You have either tried to read input from the screen or write to the keyboard, or the ADIS module has not been able to open your terminal's channels for I-O.
  • COBRT185 File malformed (Recoverable)
  • COBRT186 Attempt to open stdin, stdout or stderr with incorrect mode (Recoverable)
    You have tried to open either a standard input file with output mode, or some other file in an incorrect mode.
  • COBRT187 Run-time system not found on $COBDIR path (Fatal)
    The run-time system cannot be found on the path you have set up in the COBDIR environment variable. Alternatively, you might not have installed your COBOL system correctly.
  • COBRT188 Filename too large (Fatal)
    A file-name which you have used has more characters than the maximum number allowed by your operating system.
  • COBRT189 Intermediate code load error (Fatal)
    You are unable to load your intermediate code. You might have tried to load intermediate code that either has not been successfully produced, or has been corrupted in some way.
  • COBRT190 Too many arguments to CALL (Fatal)
    A CALL statement in your program cannot be successfully executed because of the number of arguments which you have used with it.
  • COBRT191 Terminal type not defined (Fatal)
    Your terminal is not defined.
  • COBRT192 Required terminal capability description missing (Fatal)
    A compulsory entry, for example cursor movement or clear screen, is missing from your terminal configuration database.
  • COBRT193 Error in variable length count (Fatal)
    The intermediate code which is currently being processed is not a valid operation. You are probably trying to execute a corrupt file or one which has not been produced.
  • COBRT194 File size too large (Fatal)
    A file which your program is accessing is too large for successful execution to continue.
  • COBRT195 DELETE/REWRITE not preceded by a read (Fatal)
    Before a DELETE or a REWRITE statement can be successfully executed in sequential access mode the last input-output statement executed for the associated file must have been a successful read. In your code no read statement precedes your tried DELETE or REWRITE.
  • COBRT196 Record number too large in relative or indexed file (Fatal)
    The relative record key has exceeded the system limit, that is, the file is too large for the system to handle.
  • COBRT197 Screen handling system initialization error (Fatal)
    This error can be caused by one of the following:
  • COBRT198 Load failure (Fatal)
    The system cannot load a program module or, in a multi-threading program, start a new thread.
  • COBRT199 Operating System error code lies outside expected range (Fatal)
    A system call has returned an unexpected error number which is not documented.
  • COBRT200 Run-time system internal logic error (Fatal)
    The amount of memory available on your machine is so low that not even the run-time system can be fully loaded.
Parent topic: Run-time System Error Messages


COBRT181 Invalid parameter error (Fatal)

A parameter which you have used is not one which is recognized by your system.

Resolution:

Revise your code to contain a parameter which is known by your system.

Parent topic: COBRT181 - COBRT200


COBRT182 Console input or console output open in wrong direction (Fatal)

You are either trying to read input from the screen or write to the keyboard.

Resolution:

You should recode your program.

Parent topic: COBRT181 - COBRT200


COBRT183 Attempt to open line sequential file for I-O (Fatal)

You have tried to open a line-sequential file in the input-output open mode, but this mode is not supported for files with this organization.

Resolution:

When your program has terminated you should recode your program to ensure that the file with organization line sequential is opened for input, output, or extend. You can then rerun your code.

Parent topic: COBRT181 - COBRT200


COBRT184 ACCEPT/DISPLAY I-O error (Fatal)

You have either tried to read input from the screen or write to the keyboard, or the ADIS module has not been able to open your terminal's channels for I-O.

Resolution:

Your program logic contains a mistake, so you must recode.

Parent topic: COBRT181 - COBRT200


COBRT185 File malformed (Recoverable)

Parent topic: COBRT181 - COBRT200


COBRT186 Attempt to open stdin, stdout or stderr with incorrect mode (Recoverable)

You have tried to open either a standard input file with output mode, or some other file in an incorrect mode.
Parent topic: COBRT181 - COBRT200


COBRT187 Run-time system not found on $COBDIR path (Fatal)

The run-time system cannot be found on the path you have set up in the COBDIR environment variable. Alternatively, you might not have installed your COBOL system correctly.

Resolution:

Ensure that the run-time system is on the path you have set up in the COBDIR environment variable. Alternatively, ensure that your COBOL system has been installed correctly. If it has not, you must reinstall your COBOL system.

Parent topic: COBRT181 - COBRT200


COBRT188 Filename too large (Fatal)

A file-name which you have used has more characters than the maximum number allowed by your operating system.

Resolution:

You should recode your program to check the length of the file in error, and rename it with a shorter file-name. You can then run your program again.

Parent topic: COBRT181 - COBRT200


COBRT189 Intermediate code load error (Fatal)

You are unable to load your intermediate code. You might have tried to load intermediate code that either has not been successfully produced, or has been corrupted in some way.

Resolution:

Try to obtain good intermediate code, for example, by resubmitting (or submitting) your source code to your COBOL system. You should then be able to load your code and run the program successfully.

Parent topic: COBRT181 - COBRT200


COBRT190 Too many arguments to CALL (Fatal)

A CALL statement in your program cannot be successfully executed because of the number of arguments which you have used with it.

Resolution:

When your program has terminated you can recode it using group items rather than elementary ones. You should then be able to run your program successfully.

Parent topic: COBRT181 - COBRT200


COBRT191 Terminal type not defined (Fatal)

Your terminal is not defined.

Resolution:

Your terminal type is undefined, so your operating system is unable to drive your terminal. Set up the necessary environment for your terminal.

Parent topic: COBRT181 - COBRT200


COBRT192 Required terminal capability description missing (Fatal)

A compulsory entry, for example cursor movement or clear screen, is missing from your terminal configuration database.

Resolution:

Add the missing entry to your terminal configuration database.

Parent topic: COBRT181 - COBRT200


COBRT193 Error in variable length count (Fatal)

The intermediate code which is currently being processed is not a valid operation. You are probably trying to execute a corrupt file or one which has not been produced.

Resolution:

You should resubmit your source code to your COBOL system.

Parent topic: COBRT181 - COBRT200


COBRT194 File size too large (Fatal)

A file which your program is accessing is too large for successful execution to continue.

Resolution:

When your program has terminated you should recode your program spreading the data over more than one file to ensure that no file becomes too large for your operating system to handle. Having recoded your program you can then rerun it.

Parent topic: COBRT181 - COBRT200


COBRT195 DELETE/REWRITE not preceded by a read (Fatal)

Before a DELETE or a REWRITE statement can be successfully executed in sequential access mode the last input-output statement executed for the associated file must have been a successful read. In your code no read statement precedes your tried DELETE or REWRITE.

Resolution:

When your program has terminated, recode your program, making sure that the last input-output statement to be executed before the DELETE or REWRITE is a read statement.

Parent topic: COBRT181 - COBRT200


COBRT196 Record number too large in relative or indexed file (Fatal)

The relative record key has exceeded the system limit, that is, the file is too large for the system to handle.

Alternatively, the record key which you have specified is too large for the system to deal with successfully, or the pointer to the record has been corrupted in some way so that it is either too large or it is not a multiple of the record length.

Parent topic: COBRT181 - COBRT200


COBRT197 Screen handling system initialization error (Fatal)

This error can be caused by one of the following:
  • Your display adapter is in the wrong mode.
  • Your screen handling interface has not been correctly initialized because your terminal does not have the required capabilities.
  • Memory has been incorrectly allocated.

Resolution:

The monitor must be in alphanumeric display mode rather than graphics display mode.

Parent topic: COBRT181 - COBRT200


COBRT198 Load failure (Fatal)

The system cannot load a program module or, in a multi-threading program, start a new thread.

A CALL statement has failed because:

  • In the case of a DLL, the specified entry point does not exist in the file
  • In the case of an .int or .gnt file, the file has been corrupted
  • In the case of a call of the form $PROG, name mapping has failed
  • In the case of a call-by-number library routine (CALL data-name, where data-name is a pic x with value greater than x'80'), the routine does not exist

Any call or attempt to start a thread can fail where internal structures have been corrupted; for example, by a protection violation.

A statement of the form SET PROCEDURE POINTER TO ENTRY entry-point has failed because the entry point cannot be found on disk or in the current run-unit.

The Entry Point Mapping facility has found a program on disk with the same name as an alias definition. Whether or not this condition results in a COBRT198 error depends on the setting of the entry_point_mapper_alias_exists_error tunable.

Rarely, this error can be caused by a CALL statement failing because of insufficient available memory or because the run-time system version is too old.

Resolution:

Check that the target of your call exists and has not been corrupted.

Test that a procedure pointer is valid before using it by including code of the form:

set bad-pointer to entry 'just-not-there-ever'...set procedure-pointer to entry 'myentrypoint'if procedure-pointer = bad-pointer display errorend-if
Parent topic: COBRT181 - COBRT200


COBRT199 Operating System error code lies outside expected range (Fatal)

A system call has returned an unexpected error number which is not documented.

Resolution:

Contact Technical Support who will help you to discover the specific cause of this error.

This error generates a Consolidated Tracing Facility warning event. To capture the generated event you must configure the Consolidated Tracing Facility as follows:

  • Set the trace level for the mf.rts component to WARN, INFO or DEBUG.
  • Set the API or FSYS property of the mf.rts component to TRUE.
Parent topic: COBRT181 - COBRT200


COBRT200 Run-time system internal logic error (Fatal)

The amount of memory available on your machine is so low that not even the run-time system can be fully loaded.

Alternatively, your run-time system has stopped as a result of an internal logic error from which you cannot recover.

Resolution:

Free some memory and then you should be able to run your program successfully.

Contact Technical Support who will help you to discover the cause of the error.

Parent topic: COBRT181 - COBRT200


COBRT201 - COBRT220

  • COBRT201 I-O error in paging system (Fatal)
    No room is available in your current directory or on the floppy disk which you are using, for the paging file.
  • COBRT203 CALL parameter not supplied (Fatal)
    The item you are trying to access in the Linkage Section of the currently executing program has not been initialized.
  • COBRT205 Invalid mainframe pointer value (Fatal)
    You are trying to reference an invalid mainframe address.
  • COBRT206 Reading unwritten data from memory (Fatal)
    You are trying to read data which has not been written, from the core file.
  • COBRT207 Machine does not exist (Recoverable)
    You have tried to access a machine that is not connected to your network, or which is not on-line.
  • COBRT208 Error in multi-user system (Fatal)
    This is normally caused by an unexpected error occurring in the network or file-sharing facilities. A corrupted network message also causes this error to be returned.
  • COBRT209 Network communication error (Recoverable)
    This is normally given if an incorrect checksum has been received in a communications packet.
  • COBRT210 File is closed with lock (Fatal)
    You have tried to open a file which you have previously closed with lock.
  • COBRT211 Program not executable by Run-Time System (Fatal)
    An attempt was made to run a program that is incompatible with the currently-specified run-time system. For example, system executable, shared library, and callable shared object files that have been linked using older COBOL systems could be incompatible.
  • COBRT212 Run-Time System version incompatible with object-oriented program (Fatal)
    You attempted to run an OO program that was compiled using a version of your COBOL system that is incompatible with the OO support provided in the run-time system you are using.
  • COBRT213 Too many locks (Recoverable)
    You have either tried to exceed the maximum number of simultaneous record locks per file you can have, or you have exhausted an operating system or network resource; for example dynamic memory.
  • COBRT214 GO TO has not been ALTERed (Fatal)
    You have violated one of the general rules of COBOL programming.
  • COBRT215 Cannot DEBUG a program running COMMUNICATIONS (Fatal)
    You have tried to debug a program which makes use of the communications module. This cannot be done as both Debugger and the communications module need full use of the CRT.
  • COBRT216 Cannot initialize the named communications device (Fatal)
    A device driver is probably missing.
  • COBRT217 Incompatible host for native code file (Fatal)
    The .gnt file is not valid for the host processor.
  • COBRT218 Malformed MULTIPLE REEL/UNIT file (Fatal)
    Either your file header is not correctly formatted, or you are not using a MULTIPLE REEL/UNIT file.
  • COBRT219 Operating system shared file limit exceeded (Recoverable)
    You have tried to exceed your operating system's limit on the number of shared files that you can have open simultaneously. As this figure is operating system dependent, you should consult your Release Notes for details of how many shared files your system permits to be open at any one time.
  • COBRT220 Attempt to execute more than one SORT or MERGE simultaneously (Fatal)
    You have coded your program in such a way that it is trying to execute more than one SORT or MERGE operation at the same time. For example, you might have coded a SORT statement in the input or output procedure of another SORT statement, an operation that is specifically prohibited under the rules of ANSI COBOL.
Parent topic: Run-time System Error Messages


COBRT201 I-O error in paging system (Fatal)

No room is available in your current directory or on the floppy disk which you are using, for the paging file.

Resolution:

When your program has terminated, delete any files which you no longer need from your directory to make room for the paging file, or insert a new floppy disk.

Parent topic: COBRT201 - COBRT220


COBRT203 CALL parameter not supplied (Fatal)

The item you are trying to access in the Linkage Section of the currently executing program has not been initialized.

Resolution:

Recode your program to ensure that it contains all of the necessary parameters, or check that it is a valid caller.

Parent topic: COBRT201 - COBRT220


COBRT205 Invalid mainframe pointer value (Fatal)

You are trying to reference an invalid mainframe address.

Resolution:

Check the logic of your program, and recode the appropriate statements.

Parent topic: COBRT201 - COBRT220


COBRT206 Reading unwritten data from memory (Fatal)

You are trying to read data which has not been written, from the core file.
Parent topic: COBRT201 - COBRT220


COBRT207 Machine does not exist (Recoverable)

You have tried to access a machine that is not connected to your network, or which is not on-line.

Resolution:

Make sure the machine is connected to the network and is on-line, then try to access it again.

Parent topic: COBRT201 - COBRT220


COBRT208 Error in multi-user system (Fatal)

This is normally caused by an unexpected error occurring in the network or file-sharing facilities. A corrupted network message also causes this error to be returned.

Resolution:

Retry the unsuccessful operation. If the error persists, contact Technical Support who will help you to discover the specific cause of this error.

Parent topic: COBRT201 - COBRT220


COBRT209 Network communication error (Recoverable)

This is normally given if an incorrect checksum has been received in a communications packet.

Resolution:

Your program should continue to execute after you have received this error but results might be undefined.

Parent topic: COBRT201 - COBRT220


COBRT210 File is closed with lock (Fatal)

You have tried to open a file which you have previously closed with lock.

Resolution:

Recode your program to avoid opening a file which has previously been closed with lock.

Parent topic: COBRT201 - COBRT220


COBRT211 Program not executable by Run-Time System (Fatal)

An attempt was made to run a program that is incompatible with the currently-specified run-time system. For example, system executable, shared library, and callable shared object files that have been linked using older COBOL systems could be incompatible.

On dual 32-bit/64-bit COBOL systems, all code must be compiled and linked using the same word length. A 64-bit run-time system does not run programs compiled and/or linked on 32-bit platforms or in 32-bit mode. Similarly, a 32-bit run-time system does not run programs compiled and/or linked on 64-bit platforms in 64-bit mode.

Resolution:

Recompile and/or relink your program so that it is compatible with the current run-time system.

Parent topic: COBRT201 - COBRT220


COBRT212 Run-Time System version incompatible with object-oriented program (Fatal)

You attempted to run an OO program that was compiled using a version of your COBOL system that is incompatible with the OO support provided in the run-time system you are using.

Resolution:

Recompile and/or relink your program so that it is compatible with the current run-time system.

Parent topic: COBRT201 - COBRT220


COBRT213 Too many locks (Recoverable)

You have either tried to exceed the maximum number of simultaneous record locks per file you can have, or you have exhausted an operating system or network resource; for example dynamic memory.

Resolution:

Execute a COMMIT or an UNLOCK operation on the relevant file and you should then be able to continue to run your program. You should try not to retain a record lock for longer than is necessary.

Parent topic: COBRT201 - COBRT220


COBRT214 GO TO has not been ALTERed (Fatal)

You have violated one of the general rules of COBOL programming.

Resolution:

Close any files which might be open, execute a STOP RUN statement and then edit your program to avoid such illegal operations.

Parent topic: COBRT201 - COBRT220


COBRT215 Cannot DEBUG a program running COMMUNICATIONS (Fatal)

You have tried to debug a program which makes use of the communications module. This cannot be done as both Debugger and the communications module need full use of the CRT.

Resolution:

You should run your program without the aid of Debugger.

Parent topic: COBRT201 - COBRT220


COBRT216 Cannot initialize the named communications device (Fatal)

A device driver is probably missing.

Resolution:

Ensure that all communications drivers are loaded before you try to run Communications.

Parent topic: COBRT201 - COBRT220


COBRT217 Incompatible host for native code file (Fatal)

The .gnt file is not valid for the host processor.

Resolution:

You must resubmit your program to your COBOL system.

Parent topic: COBRT201 - COBRT220


COBRT218 Malformed MULTIPLE REEL/UNIT file (Fatal)

Either your file header is not correctly formatted, or you are not using a MULTIPLE REEL/UNIT file.

Resolution:

You should try to run your program again using a backup copy of the relevant file.

Parent topic: COBRT201 - COBRT220


COBRT219 Operating system shared file limit exceeded (Recoverable)

You have tried to exceed your operating system's limit on the number of shared files that you can have open simultaneously. As this figure is operating system dependent, you should consult your Release Notes for details of how many shared files your system permits to be open at any one time.

Resolution:

Close some of the open shared files you are no longer accessing and retry the file operation.

Parent topic: COBRT201 - COBRT220


COBRT220 Attempt to execute more than one SORT or MERGE simultaneously (Fatal)

You have coded your program in such a way that it is trying to execute more than one SORT or MERGE operation at the same time. For example, you might have coded a SORT statement in the input or output procedure of another SORT statement, an operation that is specifically prohibited under the rules of ANSI COBOL.

Alternatively you are trying to sort or merge a file that is not open with the correct permissions.

Alternatively you have set the TMP environment variable to point to a directory that does not exist.

Alternatively you are trying to run a SORT with a SORTSPACE too small to do so.

Alternatively the SORTSPACE you have set is too small for the SORT you are performing.

Resolution:

Recode your program to ensure that it does not execute more than one SORT or MERGE at any one time.

Check that the files are open with the correct permissions.

Set $TMP to point to a directory that does exist or unset $TMP.

Set SORTSPACE to something more appropriate.

Either increase SORTSPACE or set SORTSCHEME=0 if it is set.

Parent topic: COBRT201 - COBRT220


COBRT221 - COBRT240

  • COBRT222 Merge files out of sequence (Fatal)
    An attempt to merge two files has been unsuccessful. One or more of your files might be out of sequence.
  • COBRT223 NLS language expansion error (Fatal)
    You have used the SORT verb, but the output buffer is not large enough.
  • COBRT224 External Language Initialization failure
  • COBRT225 Dynamic load error - program component missing (Fatal)
    The run-time system cannot locate the root or overlay of a program that is currently loaded in memory.
  • COBRT226 EXTERNAL file definition inconsistent
    Two or more programs define the same external file but with different formats. For example, maximum and minimum record lengths might be different.
  • COBRT227 EXTERNAL data definition inconsistent (Fatal)
    Two or more programs are defining the same external data item, but the first loaded program has defined the size differently from the second or subsequent loaded program.
  • COBRT228 Could not allocate memory for EXTERNAL item (Fatal)
  • COBRT229 SORT/MERGE module does not support EXTERNAL using/giving files (Recoverable)
    You have tried a SORT or MERGE operation which has USING/ GIVING files which are defined as EXTERNAL. The SORT/ MERGE module does not support USING/ GIVING files defined as EXTERNAL.
  • COBRT231 GENERATE encountered before corresponding INITIATE in report (Fatal)
    A GENERATE (Report Writer syntax) statement has been executed before a corresponding INITIATE statement.
  • COBRT232 Reference modification out of bounds
    An error has occurred because reference modification has referred to data beyond the boundaries of the base data item.
  • COBRT235 Error in debugger communications channel (Fatal)
    The Debugger has encountered system limits or conflicts resulting in communications errors. Perhaps two logins on the same UNIX system are trying to cross-session debug the same program file.
  • COBRT236 Debugged program has terminated unexpectedly (Fatal)
    A program you are debugging has terminated without following the standard run-time system shut-down process. The termination was probably either initiated by the user or caused by a severe run-time error.
  • COBRT237 Unable to initialize debugged process (Fatal)
    The Debugger has encountered system limits in starting your program. The debugged program cannot start because of either insufficient memoryor too many processes running on the UNIX system .
  • COBRT238 STOP RUN encountered during GNT animation (Informational)
    The Debugger has encountered a STOP RUN statement while debugging your .gnt code program.
  • COBRT239 Shared run-time system initialization failure (Informational)
    You are calling a COBOL module from a non-COBOL program, and have not initialized the shared run-time system.
  • COBRT240 Object reference not valid (Fatal)
    You have tried to use an object reference that contains an incorrect or non-existent object handle.
Parent topic: Run-time System Error Messages


COBRT222 Merge files out of sequence (Fatal)

An attempt to merge two files has been unsuccessful. One or more of your files might be out of sequence.

Resolution:

Make sure that the files you are trying to merge are in sequence.

Parent topic: COBRT221 - COBRT240


COBRT223 NLS language expansion error (Fatal)

You have used the SORT verb, but the output buffer is not large enough.

Resolution:

Use either the SORTNLSEXPAND or SORTNLSOVERHEAD environment variable to control the values used by SORT when calling CBL_NLS_TRANSFORM.

SORTNLSEXPAND calculates the output buffer given the input buffer.

The value of SORTNLSOVERHEAD is added to the length of the output buffer after using SORTNLSEXPAND.

The default values for both is 6.

Parent topic: COBRT221 - COBRT240


COBRT224 External Language Initialization failure

Parent topic: COBRT221 - COBRT240


COBRT225 Dynamic load error - program component missing (Fatal)

The run-time system cannot locate the root or overlay of a program that is currently loaded in memory.

Alternatively, you have insufficient memory to load your program.

Alternatively, the run-time system could not find enough file handles to open and, therefore, load the code.

Resolution:

Either the library that contained the program has been canceled, or the program is no longer available on the program search path. Ensure that the program is available either on disk or on an open library.

Either free some memory or restructure your application so that it uses less memory.

Increase your operating system file handles limit.

Parent topic: COBRT221 - COBRT240


COBRT226 EXTERNAL file definition inconsistent

Two or more programs define the same external file but with different formats. For example, maximum and minimum record lengths might be different.

Resolution

Make sure that all of your programs define the external file with the same format so that they are consistent. It is useful to have the file definition in a COPY file.

Parent topic: COBRT221 - COBRT240


COBRT227 EXTERNAL data definition inconsistent (Fatal)

Two or more programs are defining the same external data item, but the first loaded program has defined the size differently from the second or subsequent loaded program.

Resolution:

Make sure that both or all of your programs define the size of the external data item as being the same.

Parent topic: COBRT221 - COBRT240


COBRT228 Could not allocate memory for EXTERNAL item (Fatal)

Parent topic: COBRT221 - COBRT240


COBRT229 SORT/MERGE module does not support EXTERNAL using/giving files (Recoverable)

You have tried a SORT or MERGE operation which has USING/ GIVING files which are defined as EXTERNAL. The SORT/ MERGE module does not support USING/ GIVING files defined as EXTERNAL.

Resolution:

Recompile your program to use the callable SORT module (EXTSM).

Parent topic: COBRT221 - COBRT240


COBRT231 GENERATE encountered before corresponding INITIATE in report (Fatal)

A GENERATE (Report Writer syntax) statement has been executed before a corresponding INITIATE statement.

Resolution:

Correct by revising your program execution flow.

Parent topic: COBRT221 - COBRT240


COBRT232 Reference modification out of bounds

An error has occurred because reference modification has referred to data beyond the boundaries of the base data item.
Note: This error is only reported if you are using the Compiler directive setting SSRANGE"2".

Resolution:

Check your code for data items being manipulated with reference modification and ensure that the reference modification parameters are set correctly.

Parent topic: COBRT221 - COBRT240


COBRT235 Error in debugger communications channel (Fatal)

The Debugger has encountered system limits or conflicts resulting in communications errors. Perhaps two logins on the same UNIX system are trying to cross-session debug the same program file.

Resolution:

Copy the debugged program file to a different directory and try debugging.

Parent topic: COBRT221 - COBRT240


COBRT236 Debugged program has terminated unexpectedly (Fatal)

A program you are debugging has terminated without following the standard run-time system shut-down process. The termination was probably either initiated by the user or caused by a severe run-time error.

Resolution:

Run your program without debugging to determine if it runs successfully; if so, debug the program without cross-session or intrasession debugging.

Parent topic: COBRT221 - COBRT240


COBRT237 Unable to initialize debugged process (Fatal)

The Debugger has encountered system limits in starting your program. The debugged program cannot start because of either insufficient memoryor too many processes running on the UNIX system .

Resolution:

Debug your program when the load on the system has reduced. Run the program without debugging to determine if it runs successfully; if so, debug the program without cross-session or intrasession debugging. Ask your system administrator to expand the number of process slots and virtual memory page maps.

Parent topic: COBRT221 - COBRT240


COBRT238 STOP RUN encountered during GNT animation (Informational)

The Debugger has encountered a STOP RUN statement while debugging your .gnt code program.

Resolution:

Step or Zoom the debugged program, and the Debugger will terminate the program and its current session.

Parent topic: COBRT221 - COBRT240


COBRT239 Shared run-time system initialization failure (Informational)

You are calling a COBOL module from a non-COBOL program, and have not initialized the shared run-time system.

Resolution:

Ensure that your application calls the cobinit() function before executing any COBOL modules. See your COBOL System Reference for UNIX for more information about the cobinit() function.

Parent topic: COBRT221 - COBRT240


COBRT240 Object reference not valid (Fatal)

You have tried to use an object reference that contains an incorrect or non-existent object handle.

Resolution:

Ensure that the object reference uses the correct object handle, and that your program has not previously destroyed the object by sending it a Finalize message.

Parent topic: COBRT221 - COBRT240


COBRT241 - COBRT260

  • COBRT221 Internal sort error (Fatal)
  • COBRT241 Cannot instantiate an abstract class (Fatal)
    You have tried to create an instance of a class that has been declared ABSTRACT. Such classes cannot be instantiated.
  • COBRT242 Could not resolve DoesNotUnderstand message (Fatal)
    The run-time system could not resolve the DoesNotUnderstand message. This is usually because you have defined a class in such a way that this method cannot be found.
  • COBRT243 Class could not be loaded (Fatal)
    An attempt to load an object class has failed because the class does not contain a valid Class-Control section, or because the class is not defined correctly.
  • COBRT244 Licensing initialization error (Fatal)
    An error occurred initializing the run-time license.
  • COBRT245 There are no valid product licenses (Fatal)
    There are no run-time licenses installed on either the local machine or license server, or all the licenses have expired.
  • COBRT246 Maximum number of product licenses exceeded (Fatal)
    All the run-time licenses installed on either the local machine or on the license server are in use.
  • COBRT247 Licensing error (Fatal)
    A error occurred whilst trying to get a run-time license.
  • COBRT249 Process killed (signal-number) (Fatal)
    The run-time system has passed a a SIGTERM signal to a service execution process (SEP) running on an enterprise server (SIGHUP and SIGINT as well on UNIX). This may occur for one of the following reasons:
  • COBRT250 Not enough mainframe address space to load or run the program (Fatal)
    This program has been compiled with one of the compiler directives AMODE(24) or AMODE(31), which request the program's data division be registered with the Mainframe Pointer Manager. However, there is not enough free mainframe address space to allow this. For example, if you have compiled with the AMODE(24) compiler directive, the total address space required for your program's data division should not exceed 16 megabytes.
  • COBRT251 Attempt to load AMODE(24) program when current setting is AMODE(31) only (Fatal)
    The settings for the current project indicate that only AMODE(31) programs can be invoked, but an attempt was made to invoke an AMODE(24) program.
  • COBRT252 Memory corruption detected (Fatal)
    The run-time system has detected a memory corruption in a block of memory that it had previously allocated.
  • COBRT253 Cannot load file - unsupported format (Fatal)
    The file specified is not recognized as a format that the run-time system can load and execute.
  • COBRT254 Keyboard interrupt to ANIMATOR during ACCEPT (Fatal)
    While using Animator you have terminated your program with a keyboard interrupt.
Parent topic: Run-time System Error Messages


COBRT221 Internal sort error (Fatal)

Resolution:

Contact Technical Support who will help you to discover the cause of the error and how it can be rectified.

Parent topic: COBRT241 - COBRT260


COBRT241 Cannot instantiate an abstract class (Fatal)

You have tried to create an instance of a class that has been declared ABSTRACT. Such classes cannot be instantiated.

Resolution:

Ensure that you have specified the correct class name. Check to see if there is a subclass that you should use instead.

Parent topic: COBRT241 - COBRT260


COBRT242 Could not resolve DoesNotUnderstand message (Fatal)

The run-time system could not resolve the DoesNotUnderstand message. This is usually because you have defined a class in such a way that this method cannot be found.

Resolution:

Check the logic in your program to ensure that it invokes only methods that are supported by the object, or ensure that the object supports the DoesNotUnderstand method.

Parent topic: COBRT241 - COBRT260


COBRT243 Class could not be loaded (Fatal)

An attempt to load an object class has failed because the class does not contain a valid Class-Control section, or because the class is not defined correctly.

Resolution:

Check the definition of the class.

Parent topic: COBRT241 - COBRT260


COBRT244 Licensing initialization error (Fatal)

An error occurred initializing the run-time license.

Additional information regarding this error is available in a CTF trace.

Resolution

Ensure that the license server installer is run on the local machine.

Parent topic: COBRT241 - COBRT260


COBRT245 There are no valid product licenses (Fatal)

There are no run-time licenses installed on either the local machine or license server, or all the licenses have expired.

Resolution

Run the License System Administration tool CESAdminTool and install run-time licenses.

Parent topic: COBRT241 - COBRT260


COBRT246 Maximum number of product licenses exceeded (Fatal)

All the run-time licenses installed on either the local machine or on the license server are in use.

Resolution

Run the License System Administration tool CESAdminTool and install additional run-time licenses.

Parent topic: COBRT241 - COBRT260


COBRT247 Licensing error (Fatal)

A error occurred whilst trying to get a run-time license.

Additional information is displayed after the error message and/or in a CTF trace.

Resolution

Either run the CESAdminTool on the local machine or resolve any issues on the license server or with the network.

Parent topic: COBRT241 - COBRT260


COBRT249 Process killed (signal-number) (Fatal)

The run-time system has passed a a SIGTERM signal to a service execution process (SEP) running on an enterprise server (SIGHUP and SIGINT as well on UNIX). This may occur for one of the following reasons:
  • Implicitly as part of MSS's runaway task processing when the server manager notices that a CICS transaction appears to be looping.
  • Explicitly on UNIX if you execute a kill -s TERM pid command (where pid is the process ID of the SEP). You might do this if you see a SEP consuming a lot of CPU.

Resolution:

Investigate the reason for the service or CICS transaction looping, for example, by analysing enterprise server dumps or traces, or by animating the service or transaction.

Parent topic: COBRT241 - COBRT260


COBRT250 Not enough mainframe address space to load or run the program (Fatal)

This program has been compiled with one of the compiler directives AMODE(24) or AMODE(31), which request the program's data division be registered with the Mainframe Pointer Manager. However, there is not enough free mainframe address space to allow this. For example, if you have compiled with the AMODE(24) compiler directive, the total address space required for your program's data division should not exceed 16 megabytes.

Resolution:

Reduce the amount of mainframe address space required by cancelling any other AMODE programs that are not currently in use.

Parent topic: COBRT241 - COBRT260


COBRT251 Attempt to load AMODE(24) program when current setting is AMODE(31) only (Fatal)

The settings for the current project indicate that only AMODE(31) programs can be invoked, but an attempt was made to invoke an AMODE(24) program.

Resolution:

Either change the current project settings to allow for the invocation of AMODE(24) programs, or recompile the program that was causing the error as AMODE(31).

Parent topic: COBRT241 - COBRT260


COBRT252 Memory corruption detected (Fatal)

The run-time system has detected a memory corruption in a block of memory that it had previously allocated.

Resolution:

You need to isolate the actual point in execution where the memory corruption occurs the investigate the cause. To do this you could:

  • Run with a memory strategy that indicates that memory is to be validated each time an allocation or free operation occurs (will have a major effect on performance)
  • Add calls to CBL_MEM_VALIDATE() at appropriate points in the application
Parent topic: COBRT241 - COBRT260


COBRT253 Cannot load file - unsupported format (Fatal)

The file specified is not recognized as a format that the run-time system can load and execute.
Parent topic: COBRT241 - COBRT260


COBRT254 Keyboard interrupt to ANIMATOR during ACCEPT (Fatal)

While using Animator you have terminated your program with a keyboard interrupt.
Parent topic: COBRT241 - COBRT260


Tools

  • Introduction to the Consolidated Tracing Facility
  • FaultFinder
  • Profiler
  • Rebuild
    Rebuild is a file management utility invoked from the command line. It enables you to perform a number of actions on indexed data files, such as repairing or reorganizing them.
Parent topic: Micro Focus COBOL Server for UNIX


Introduction to the Consolidated Tracing Facility

The Consolidated Tracing Facility (CTF) is a tracing infrastructure that enables you to quickly and easily produce diagnostic information detailing the operation of Micro Focus software components and your own programs.

To create tracing information using CTF, you need to set up the environment appropriately.

You also need to create a side file, the CTF configuration file, to define the tracing information you want to capture. For example, you can define:

  • The application to trace. Tracing information of a number of Micro Focus software components can be enabled. See Components Traced by CTF .

    You can also produce tracing information for your own programs by using library routines that give you access to CTF infrastructure. See Consolidated Tracing Facility Routines.

  • The severity level of tracing messages to capture. See CTF Configuration File.
  • The emitters to produce the tracing information (such as text or binary). See Emitter List.

    If you choose binary tracing, you can use the CTF Viewer to examine binary format trace files easily. See CTF Viewer.

  • To enable CTF tracing
  • CTF Trace File Formats
  • CTF Viewer
  • Components Traced by CTF
  • Configuration File for CTF
  • Emitter List
  • Tracing Examples
Parent topic: Tools


To enable CTF tracing

  1. Set the MFTRACE_CONFIG environment variable to point to the configuration file, before you invoke the application. For example:
    export MFTRACE_CONFIG=/home/usr/ctf/ctf.cfg
  2. Specify the format of CTF trace files you require by adding the appropriate lines in the configuration file ctf.cfg, or, if developing .NET managed code, a configuration file app.cfg located in the same folder as the associated app.exe file, such as:
    mftrace.dest = binfile
mftrace.emitter.binfile#location  = /home/usr/logs
mftrace.level.mf.rts              = info
mftrace.comp.mf.rts#pgm           = true
mftrace.comp.mf.rts#pgmload       = true
mftrace.comp.mf.rts#syspgm        = true
  3. Set the MFTRACE_LOGS environment variable to specify the location in which to create the CTF log files. If MFTRACE_LOGS is not set, the current folder is used.
  4. Run the application from the environment you set up.
  5. If you are using the .NET environment, instead of setting the MFTRACE_CONFIG variable you can configure CTF tracing in an app.config file in the same folder as its associated app.exe file. The configuration statements must be inserted in an <mftrace_config> section in the <configSections> as CDATA. For example:
    <?xml version ="1.0"?>
  <configuration>
    <configSections>
      <sectionGroup name="MicroFocus.COBOL.Tracing">
        <section name="mftrace_config"
         type="MicroFocus.COBOL.Runtime.CdataSectionHandler,
         MicroFocus.COBOL.Runtime.Win32,Version=4.0.0.0,Culture=neutral,
         PublicKeyToken=0412c5e0b2aaa8f0" />
      </sectionGroup>
    </configSections>
    <MicroFocus.COBOL.Tracing>
      <mftrace_config>
        <![CDATA[>
mftrace.dest                           = binfile
mftrace.emitter.binfile#location       = c:\logs
mftrace.level.mf.rts                   = info
mftrace.comp.mf.rts#pgm                = true
mftrace.comp.mf.rts#pgmload            = true
mftrace.comp.mf.rts#syspgm             = true
        <]]>
      </mftrace_config>
    </MicroFocus.COBOL.Tracing>
  </configuration>
    Note: If the MFTRACE_CONFIG variable is set, CTF will use it in preference to an app.config file.
Parent topic: Introduction to the Consolidated Tracing Facility


CTF Trace File Formats

You can view the results of a trace in one of two formats. The default is as a simple text file, or you can create a compressed binary file, which can be viewed using the CTF Viewer.

Text format trace files have the advantage that you can view them in a text editor, but there are a number of disadvantages:

  • Trace files can get very large very quickly.
  • The trace record format needs to be specified before tracing begins (e.g. when tracing a multi-threaded application, the $(THREAD) pseudo-variable needs to be specified to ensure that the thread id appears in each trace record).
  • Trace events are meaningless to nearly everyone except the developer who trace-enabled the application/component.

Binary format trace files cannot be viewed in a text editor, but they provide the following advantages:

  • Compressed format. Usually at least 50% the size of an equivalent text-format trace file.
  • No record format needs to be specified before tracing begins. All relevant information about a trace event is recorded, such as the process id, thread id, date, time, component id, event id, trace data and so on.

You can view binary format trace files using the CTF Viewer.

Parent topic: Introduction to the Consolidated Tracing Facility
Related concepts
Example CTF Configuration Files
Related reference
TEXTFILE Emitter Properties
BINFILE Emitter Properties


CTF Viewer

The Consolidated Tracing Facility (CTF) Viewer is a tool for viewing binary format trace files that were created by configuring the CTF BINFILE emitter..

The CTF Viewer enables you to:

  • Navigate a trace file using the usual arrow and navigation keys
  • Display annotations for trace events to give them meaningful descriptions
  • Display more details of the selected event in the Properties view
  • Open more than one trace file at a time, with each trace file being opened in a separate editor tab
  • Set CTF preferences to control annotation file locations, and automatic switching to the CTF perspective
  • Use bookmarks for quick navigation
  • Perform text searches

To use the CTF Viewer, you need to create trace files in binary format and to set up your environment and CTF configuration file appropriately.

  • Annotation Files for CTF Events
  • Bookmarks in the CTF viewer
  • To create and load a binary trace file into the CTF Viewer
  • To search in the CTF Viewer
Parent topic: Introduction to the Consolidated Tracing Facility


Annotation Files for CTF Events

The CTF Viewer enables you to display trace files using annotations to replace component identifiers such as “MF.RTS” and event identifiers such as “6” with more meaningful textual descriptions.

Annotation files are supplied in the $COBDIR/etc/mftrace/annotations directory. There is one annotations file for each supported component.

Parent topic: CTF Viewer


Bookmarks in the CTF viewer

You can set bookmarks on events in a trace file, when you are using the CTF Viewer. Bookmarks enable you to navigate quickly. Bookmarks behave as follows:

  • You can add a bookmark to an event, by right-clicking the event and clicking Add Bookmark.
  • Bookmarked events are shown in the main CTF View by a blue bookmark icon in column one of the event. They are also displayed in the Bookmarks view.
  • Double-click a bookmark in the Bookmarks view to jump to the bookmarked event in the Viewer. If the bookmarked event is in a file that isn't open, the file is automatically opened.
  • You can select multiple events in the main CTF view and set bookmarks on them all. You can also select multiple bookmarked events and remove their bookmarks.
  • Bookmarks persist between IDE sessions.
Parent topic: CTF Viewer
Related concepts
CTF Trace File Formats
Example CTF Configuration Files


To create and load a binary trace file into the CTF Viewer

  1. Enable CTF tracing.
  2. Configure CTF to generate a binary trace file when the application is run, by adding the following lines to the configuration file ctf.cfg:
    mftrace.dest                     = binfile
mftrace.emitter.binfile#location = <directory in which to write the trace file>
  3. Run the application.
  4. Click File > Open File, and then double-click the trace file you want.

    Alternatively you can create a project containing the trace files.

    1. Create a new project of the General type.
    2. Follow the wizard, and when it asks for the location of your files, specify the directory containing your trace files. We recommend that you specify the trace file location defined in the mftrace.emitter.binfile#location entry in your CTF configuration file.
    3. In the COBOL Explorer view, double-click a trace file to load it into the viewer.
Parent topic: CTF Viewer
Related concepts
CTF Trace File Formats
Example CTF Configuration Files


To search in the CTF Viewer

  1. Right-click in the CTF Viewer.
  2. Click Find.
  3. Enter your search string in the Find field, using the normal search features.
  4. Click Find.
Note:
  • You can use only Find capabilities and not Replace ones, since the trace file is loaded as a read-only file.
  • When you search for a text string, each row in the viewer is treated as a single text string, with each column in a row separated by a single space character. For example, a row with the following information is treated as a single text string for searching purposes:
    12:17:35.630 COBOL Runtime System 504 Library Load 0 0 C:\nx50\Base\BIN\UTILS.lbr
  • You can also use Find from the Edit menu.
  • You can use keys for Find next (Ctrl+K) and Find previous (Shift+Ctrl+K).
Parent topic: CTF Viewer
Related concepts
CTF Trace File Formats
Example CTF Configuration Files


Components Traced by CTF

The Consolidated Tracing Facility (CTF) can produce tracing information for the components listed below:

  • mf.esmq Properties
    This component provides calls to the MQSeries XA switch module.
  • mf.mffh.fs Properties
    This component provides Fileshare processing.
  • mf.mffh.xfh Properties
    This component provides the Micro Focus File Handler system.
  • mf.mffh.xsm Properties
    This component provides the Micro Focus Sort module.
  • mf.rts Properties
    This component provides behavior of the run-time system.
Parent topic: Introduction to the Consolidated Tracing Facility


mf.esmq Properties

This component provides calls to the MQSeries XA switch module.

The following table lists the properties of the mf.esmq component and shows the event information that can be included in the trace for each property.

Property | Property Description | Level | Event Id | Event Description
ALL | Enables all of the tracing properties | - | - | -
MQLOAD | Switch load file events | DEBUG | 3 | Switch load file loaded
START | Start of work units | DEBUG | 3 | Unit of work started
END | End of work units | DEBUG | 3 | Unit of work finished
OPEN | Opening of MQI channels | DEBUG | 3 | MQI channel to the server queue manager opened
CLOSE | Closing of MQI channels | DEBUG | 3 | MQI channel to the server queue manager closed
COMMIT | Commit decisions | DEBUG | 3 | Decision made to commit the unit of work
ROLLBACK | Rollback decisions | DEBUG | 3 | Decision made to rollback the unit of work
PREPARE | Commit preparation | DEBUG | 3 | Preparation to commit the unit of work started
Parent topic: Components Traced by CTF


mf.mffh.fs Properties

This component provides Fileshare processing.

The following table lists the properties of the mf.mffh.fs component and shows the event information that can be included in the trace for each property.

ALL
Enables all of the XFH properties
FILE:*
Enable/Disable tracing on all files.
FILE: <filename>
Enable/Disable tracing on specific file
BASE
Base events.
Level | Event Id | Event Description
DEBUG/INFO | 200 | Entry
DEBUG/INFO | 201 | Exit
COMMS
COMMS Call (Send receive in FHRSUB only).
Level | Event Id | Event Description
DEBUG | 202 | COMMS Entry
DEBUG | 203 | COMMS Return
Parent topic: Components Traced by CTF


mf.mffh.xfh Properties

This component provides the Micro Focus File Handler system.

The following table lists the properties of the mf.mffh.xfh component and shows the event information that can be included in the trace for each property.

ALL
Enables all of the XFH properties
FILE:*
Enable/Disable tracing on all files.
FILE: <filename>
Enable/Disable tracing on specific file
BASE
Enable/Disable base events.
Level | Event Id | Event Description
INFO | 1 | Entry
INFO | 2 | Exit
INFO | 3 | Call File Handler
INFO | 4 | File Handler Exit
INFO | 5 | Initialization Start
INFO | 6 | Initialization End
INFO | 7 | Final Start
INFO | 8 | Final End
INFO | 9 | Processing other Exit
INFO | 11 | Base Entry Point
INFO | 18 | Call Module
DEBUG | 19 | Allocate Handle
DEBUG | 20 | De-allocate Handle
DEBUG | 21 | Dynamic Custom File Handler Library loaded
DEBUG | 22 | Dynamic Custom File Handler Load Failure
DEBUG | 23 | Dynamic Custom File Handler Loaded
DEBUG | 24 | Dynamic Custom File Handler Environment Parsing Failure
DEBUG | 25 | Dynamic Custom File Handler environment set
MEMORY
Memory allocation and de-allocation events.
Level | Event Id | Event Description
DEBUG/ERROR | 12 | Memory allocated
DEBUG/ERROR | 13 | Memory Re-allocated
BSIO
Byte Steam layer events.
Level | Event Id | Event Description
INFO | 100 | Open
INFO | 101 | Open output
INFO | 102 | Delete
INFO | 103 | Copy
INFO | 104 | Rename
INFO | 105 | Close
INFO | 106 | Read
INFO | 107 | Seek end
INFO | 108 | Write
INFO | 109 | Set sema
INFO | 110 | Release sema
INFO | 111 | Lock file
INFO | 112 | Unlock file
INFO | 113 | Unlock
INFO | 114 | Test lock
INFO | 115 | Get lock
INFO | 116 | Release lock
INFO | 117 | Flush file
INFO | 118 | Configuration info
INFO | 119 | Message
INFO | 120 | Pass through
INFO | 121 | Get parameters
JSEB
Calls to JSEB events.
Level Event Id Event Description
- 16 JSEB Base
CATALOG
Calls to Catalog events.
Level Event Id Event Description
- 17 Catalog Base
CONFIG
Configuration setting events.
Level | Event Id | Event Description
INFO | 10 | Processing name
INFO | 14 | Change Processing name
INFO | 15 | 9/139 Error
Parent topic: Components Traced by CTF


mf.mffh.xsm Properties

This component provides the Micro Focus Sort module.

The following table lists the properties of the mf.mffh.xsm component and shows the event information that can be included in the trace for each property.

Property | Property Description | Level | Event Id | Event Description
ALL |  | - | - | Enables all of the XFH properties
 |  | DEBUG | 1 | EXTSM Entry
 |  |  | 2 | EXTSM Exit
 |  |  | 300 | Flush temp file

Parent topic: Components Traced by CTF


mf.rts Properties

This component provides behavior of the run-time system.

The following table lists the properties of the mf.rts component and shows the event information that can be included in the trace for each property.

no property
Event Level | Event Id | Event Description
INFO | 128 | Start of run-time system initialization. This event applies to native COBOL only.
INFO | 129 | End of run-time system initialization
INFO | 130 | Start of run-time system de-initialization
INFO | 131 | End of run-time system de-initialization
INFO | 132 | Entered a COBOL container. This event applies to native COBOL only.
INFO | 133 | Exited a COBOL container. This event applies to native COBOL only.
INFO | 134 | Link level entered. This event applies to .NET managed code only.
INFO | 135 | Link level exited. This event applies to .NET managed code only.
INFO | 136 | Memory validating. This event applies to native COBOL only.
INFO | 137 | Memory validated. This event applies to native COBOL only.
INFO | 254 | STOP RUN
ERROR | 255 | Run-time system error
ALL
Enables/disables all of the other properties.
API
This property is for .NET managed code only. API events:
Event Level | Event Id | Event Description
INFO | 56 | Entry to API. This event applies to native COBOL only..
INFO | 57 | Exit from API.
CONFIG
This property is for native COBOL only. Run-time configuration event:
Event Level | Event Id | Event Description
INFO | 61 | Run-time configuration operation (e.g. cobconfig file location and entries).
CONTAINER
This property is for native COBOL only. COBOL container events:
Event Level | Event Id | Event Description
DEBUG | 40 | Server initialization (start/finish)
DEBUG | 41 | Server de-initialization (start/finish)
DEBUG | 42 | Server context initialization (start/finish)
DEBUG | 43 | Server callback (start/finish)
DEBUG | 49 | Request handler function (start/finish)
INFO | 9 | Initializing environment for application running in the COBOL container (start/finish)
INFO | 10 | Invoking application in the COBOL container (start/finish)
INFO | 11 | Restoring initial state following the execution of an application in the COBOL container (start/finish)
INFO | 25 | Request handler trace event
INFO | 46 | Service lookup callback (start/finish)
ERROR | 0 | Request handler "start/next request" error
ERROR | 1 | Request handler "response" error
ERROR | 2 | Request handler "end processing" error
ERROR | 3 | Error loading the main program of the application identified by the request handler "start/next request"
ERROR | 4 | Error loading the package containing the application identified by the request handler "start/next request"
ERROR | 5 | Syncpoint failure
ERROR | 12 | Application termination due to exit from Debugger
ENV
This property applies to native COBOL only. Environment variable events:
Event Level | Event Id | Event Description
INFO and WARN | 60 | Environment variable operation
EXTERNAL
External data events.
Event Level | Event Id | Event Description
INFO | 26 | External data item created
INFO | 27 | External data item destroyed. This event applies to native COBOL only.
ERROR | 28 | External data item size mismatch
FSYS
This property is for native COBOL only. Low-level I/O level events:
Event Level | Event Id | Event Description
INFO | 52 | Entry to I/O function
INFO | 53 | Exit from I/O function
INFO | 54 | Specific I/O operation
MEMORY
This property applies to native COBOL only. Memory allocation and de-allocation events:
Event Level | Event Id | Event Description
INFO | 13 | Memory allocated
INFO | 14 | Memory freed
INFO | 15 | Memory re-allocated (resized)
INFO | 16 | Re-allocated memory freed
INFO | 17 | Memory remaining allocated at RTS termination
ERROR | 48 | Insufficient low-memory available for PL/I. This property is for native COBOL only.
ERROR | 248 | Memory allocation failure
ERROR | 249 | Memory corruption detected
MFENTMAP
This property applies to native COBOL only. Entry Point Mapper event:
Event Level | Event Id | Event Description
INFO | 55 | Entry Point Mapper function
MFPM
This property applies to native COBOL only. Mainframe Pointer Manager events (AMODE programs):
Event Level | Event Id | Event Description
INFO | 29 | Absolute memory registration
INFO | 30 | External data registration
INFO | 31 | Memory registration
INFO | 32 | Working-storage memory registration
INFO | 33 | External data de-registration
INFO | 34 | Memory de-registration
INFO | 35 | Working-storage memory de-registration
INFO | 36 | Local-storage memory registration
INFO | 37 | Local-storage memory de-registration
ERROR | 250 | MFPM error.
PGM
User program entry, exit, chain, and link events:
Event Level | Event Id | Event Description
INFO | 6 | Program entry
INFO | 7 | Program exit
INFO | 8 | Program chain. This event applies to native COBOL only.
INFO | 18 | Program link. This event applies to native COBOL only.
PGMLOAD
Program load events:
Event Level | Event Id | Event Description
DEBUG | 50 | Subsystem function. This event applies to native COBOL only.
INFO | 19 | .int or .gnt program load
INFO | 20 | Logical cancel
INFO | 21 | Physical cancel. This event applies to native COBOL only.
INFO | 22 | Logical canceled program made live again. This event applies to native COBOL only.
INFO | 23 | DLL or shared object load. This event applies to native COBOL only.
INFO | 24 | DLL or shared object unload. This event applies to native COBOL only.
INFO | 38 | .lbr load. This event applies to native COBOL only.
INFO | 39 | .lbr unload. This event applies to native COBOL only.
ERROR | 251 | Program load error. This event applies to native COBOL only.
PGMSEARCH
Program searcher events:
Event Level | Event Id | Event Description
DEBUG | 58 | Entry to program searcher.
DEBUG | 59 | Exit from program searcher.
SIGNAL
This property applies to native COBOL only. Signal handling events:
Event Level | Event Id | Event Description
ERROR | 252 | Apply previously ‘held’ signal
ERROR | 253 | Signal caught
SYSPGM
System program entry, exit, chain, and link events:
Event Level | Event Id | Event Description
INFO | 6 | Program entry
INFO | 7 | Program exit
INFO | 8 | Program chain. This event applies to native COBOL only.
INFO | 18 | Program link. This event applies to native COBOL only.
THREAD
Threading and synchronization events:
Event Level | Event Id | Event Description
INFO | 56 | Entry to API (Threading and synchronization APIs)
INFO | 57 | Exit from API (Threading and synchronization APIs)
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF


Configuration File for CTF

You can configure the behavior of CTF using the CTF configuration file ctf.cfg, whose location is set in the MFTRACE_CONFIG environment variable. If you are using the .NET environment, you can alternatively use an app.config file located in the folder containing the associated app.exe file.

CTF configuration files are processed during run-time system initialization and must be text files. You specify the configuration information as name-value pair entries, with each entry on a separate line, and with lines beginning with ‘#’ treated as comments.

You can use the following entries in configuration files:

  • mftrace.application
    Restricts tracing to a specific application.
  • mftrace.comp.component-name#property
    Sets a component's property.
  • mftrace.dest
    Specifies the default output destinations that are to be used when tracing. If you specify multiple mftrace.dest definitions for a given emitter in the configuration file their effect is cumulative.
  • mftrace.dest.component-name
    Specifies additional (or replacement) output destinations that are to be used when tracing a component.
  • mftrace.emitter.emitter-name#property
    Sets an emitter property.
  • mftrace.level
    Specifies the default tracing level to use for all components.
  • mftrace.level.component-name
    Specifies the tracing level to use for a single component.
  • Example CTF Configuration Files
Parent topic: Introduction to the Consolidated Tracing Facility


mftrace.application

Restricts tracing to a specific application.

Syntax:

mftrace.application=executable-name

Parameters:

executable-name
The name of the executable for the application for which tracing is to be performed. This can be either a fully-qualified or unqualified name. Enclosing the executable name within parentheses indicates that the application is being run under a trigger program (such as cobrun ), and that the second program of the command line is to be used as the real executable name.

Default:

All applications are traceable if you do not set mftrace.application.

Comments:

Use mftrace.application to restrict tracing to a specific application. If the name of the application's executable does not match executable-name, all preceding configuration entries are ignored and the remainder of the configuration file is not processed.

Examples:

To restrict tracing to the myapp executable:

...
mftrace.application=myapp
...

To restrict tracing to the otherapp executable being run under a trigger program:

...
mftrace.application=(otherapp)
...
Parent topic: Configuration File for CTF


mftrace.comp.component-name#property

Sets a component's property.

Syntax:

mftrace.comp.component-name#property-name=property-value

Parameters:

component-name
The name of the component for which the property is to be set. See Component List for a list of available components.
property-name
The name of the component property to set.
property-value
The value of the component property to be set.
If any of the following well-known property case-insensitive values are used, they are held in two forms: the string as given, and a corresponding numeric value. A component can then use CBL_CTF_COMP_PROPERTY_GET to retrieve the numeric value of the property directly without needing to perform its own string conversion.
String Value | Maps to
ON | 1
OFF | 0
YES | 1
Y | 1
NO | 0
N | 0
TRUE | 1
FALSE | 0
ENABLED | 1
DISABLED | 0
numeric-string | n

Component names and property names are case insensitive.

Default:

The properties and their associated values depend on the component.

Comments:

Use mftrace.comp.component-name#property to set the property with the given name and value for the given component. You can set any property name and value, regardless of whether the component actually makes use of it.

You can specify multiple mftrace.comp.component-name#property entries in the configuration file, but an entry that specifies a property for a component that has previously been set overrides the previous property value.

Properties are intended to be used for defining the areas of tracing that are required for the component.

Examples:

To set the Memory and PgmLoad properties for the mf.rts component:

...
mftrace.comp.mf.rts#memory=on
mftrace.comp.mf.rts#pgmload=enabled
...
Parent topic: Configuration File for CTF
Related information
Components Traced by CTF
mf.rts Component Properties
To enable CTF tracing
Configuration File for CTF


mftrace.dest

Specifies the default output destinations that are to be used when tracing. If you specify multiple mftrace.dest definitions for a given emitter in the configuration file their effect is cumulative.

Syntax:

mftrace.dest=emitter-list

Parameters:

emitter-list
A list of comma- or space-separated emitter names. See Emitter List for a list of available emitters.

Emitter names are case-insensitive.

Default:

mftrace.dest=TEXTFILE

Comments:

TEXTFILE is assumed if no mftrace.dest entry is specified in the configuration file.

Examples:

To specify that tracing events are to be output to file in binary format:

...
mftrace.dest=BINFILE
...

To specify that tracing events are to be output to file in text format and also in binary format:

...
mftrace.dest=TEXTFILE,BINFILE
...

or alternatively:

...
mftrace.dest=TEXTFILE
mftrace.dest=BINFILE
...
Parent topic: Configuration File for CTF
Related information
Emitter List
To enable CTF tracing
Configuration File for CTF


mftrace.dest.component-name

Specifies additional (or replacement) output destinations that are to be used when tracing a component.

Syntax:

mftrace.dest.component-name=[(]emitter-list[)]

Parameters:

component-name
The component whose trace entries are to be routed to the output destinations identified by emitter-list.
emitter-list
A list of comma-or space-separated emitter names. See Emitter List for a list of available emitters.

If emitter-list is enclosed in parentheses, the component’s trace events will only be routed to those output destinations specified by emitter list and not to any inherited from its parent.

Emitter names are case-insensitive.

Default:

If not set, a component’s output destinations are inherited from its parent.

Comments:

If you specify multiple mftrace.dest.component-name definitions for a given component in the configuration file their effect is cumulative.

Examples:

To specify that tracing events from the mf.rts component are output to a binary file in addition to the default text file that trace events from all other components will be output to. All components that inherit from the mf.rts component (such as mf.rts.err and mf.rts.mem) also have their trace events routed to the a binary file and the default text file:

...
mftrace.level=INFO
mftrace.dest=TEXTFILE
mftrace.dest.MF.RTS=BINFILE
...

To specify that tracing events from the mf.rts component are to be output only to a binary file. All components that inherit from the mf.rts component (such as mf.rts.err and mf.rts.mem) also have their trace events output only to a binary file. All other components’ trace events are output to the default text file:

...
mftrace.level=INFO
mftrace.dest=TEXTFILE
mftrace.dest.MF.RTS=(BINFILE)
...
Parent topic: Configuration File for CTF
Related information
Emitter List
To enable CTF tracing
Configuration File for CTF


mftrace.emitter.emitter-name#property

Sets an emitter property.

Syntax:

mftrace.emitter.emitter-name#property-name=property-value

Parameters:

emitter-name
The name of the emitter for which the property is to be set.
property-name
The name of the emitter property to set.
property-value
The value of the emitter property to be set.
If any of the following property case-insensitive values are used, they are held in two forms: the string as given, and a corresponding numeric value. A component can then use CBL_CTF_EMITTER_PROPERTY_GET to retrieve the numeric value of the property directly without needing to perform its own string conversion.
String Value | Maps to
ON | 1
OFF | 0
YES | 1
Y | 1
NO | 0
N | 0
TRUE | 1
FALSE | 0
ENABLED | 1
DISABLED | 0
numeric-string | n

Emitter names and property names are case insensitive.

Default:

The properties and their associated values depend on the emitter.

Comments:

Use mftrace.emitter.emitter-name#property to set the property with the given name and value for the given emitter. You can set any property name and value, regardless of whether the emitter actually makes use of it.

You can specify multiple mftrace.emitter.emitter-name#property entries in the configuration file, but an entry that specifies a property for an emitter that has previously been set overrides the previous property value.

Examples:

To set the trace file name, the number of backup files, and the maximum size of each file in the backup set for the TEXTFILE emitter:

...
mftrace.emitter.textfile#location=e:\logs
mftrace.emitter.textfile#file=mytrace.dat_$(GEN)
mftrace.emitter.textfile#maxgeneration=3
mftrace.emitter.textfile#maxfilesize=200
...

This specifies that mytrace.dat, mytrace.dat_1, mytrace.dat_2, and mytrace.dat_3 would be created in the directory e:\mylogs and each of these files would have a maximum size of 200 Kb.

Parent topic: Configuration File for CTF
Related information
Emitter List
To enable CTF tracing
Configuration File for CTF


mftrace.level

Specifies the default tracing level to use for all components.

Syntax:

mftrace.level=trace-threshold-level

Parameter:

trace-threshold-level
One of the following case-insensitive values:
NONE | No events are to be traced.
DEBUG | All events are traced. This produces the most verbose output.
INFO | All INFO, WARN, ERROR, and FATAL events are traced.
WARN | All WARN, ERROR, and FATAL events are traced
ERROR | All ERROR and FATAL events are traced
FATAL | Only FATAL events are traced

Default:

mftrace.level=NONE

Comments:

You can specify multiple mftrace.level entries in the configuration file, but an entry specifying a level overrides any level previously specified.

You can override this default tracing level by using mftrace.level.component entries.

Examples:

To set the INFO tracing threshold level:

...
mftrace.level=info
...
Parent topic: Configuration File for CTF
Related information
To enable CTF tracing
Configuration File for CTF


mftrace.level.component-name

Specifies the tracing level to use for a single component.

Syntax:

mftrace.level.component-name=trace-threshold-level

Parameters:

component-name
The component whose trace threshold level is to be set. Component names are case-insensitive.
trace-threshold-level
One of the following case-insensitive values:
NONE
No events are to be traced.
DEBUG
All events are traced. This produces the most verbose output.
INFO
All INFO, WARN, ERROR, and FATAL events are traced.
WARN
All WARN, ERROR, and FATAL events are traced
ERROR
All ERROR and FATAL events are traced
FATAL
Only FATAL events are traced

Default:

If not set, a component’s trace threshold level is inherited from its parent, or the default trace level if the component does not have a parent. A component's parent is the component that appears to the left of it in component-name. For example, if component-name is mf.rts.subsystem, mf is the parent of rts, and rts is the parent of subsystem.

Comments:

Use mftrace.level.component to specify the level of tracing that is to be performed by the specified component and any components that inherit from it. You can specify multiple mftrace.level.component entries in the configuration file, but an entry that specifies a tracing level for a component that has previously been set overrides the previous setting.

Examples:

To set the WARN tracing threshold level for the mf.rts component and the DEBUG tracing threshold level for all other components:

...
mftrace.level=debug
mftrace.level.mf.rts=warn
...
Parent topic: Configuration File for CTF
Related information
Components Traced by CTF
To enable CTF tracing
mftrace.application
mftrace.comp.component-name#property
mftrace.emitter.emitter-name#property
mftrace.level


Example CTF Configuration Files

Example ctf.cfg file 1

This configuration file traces the COBOL programs' loads, entries, exits and cancels, and creates a text file:

mftrace.emitter.textfile#Format = $(TIME) $(THREAD) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)
mftrace.level.mf.rts              = info
mftrace.comp.mf.rts#pgm           = true
mftrace.comp.mf.rts#pgmload       = true
mftrace.comp.mf.rts#syspgm        = true

Example ctf.cfg file 2

This configuration file traces the COBOL programs' loads, entries, exits and cancels, and creates a text file:

mftrace.dest                      = binfile
mftrace.emitter.binfile#location  = /user/bin/logs
mftrace.level.mf.rts              = info
mftrace.comp.mf.rts#pgm           = true
mftrace.comp.mf.rts#pgmload       = true
mftrace.comp.mf.rts#syspgm        = true

where:

  • /user/bin/logs is the location where the trace files for the application is created.
  • binfile indicates that a binary trace file is to be generated

Example app.config file

(For .NET environment only.) This configuration file traces the COBOL programs' loads, entries, exits and cancels, and creates a text file:

<?xml version ="1.0"?>
  <configuration>
    <configSections>
      <sectionGroup name="MicroFocus.COBOL.Tracing">
        <section name="mftrace_config"
         type="MicroFocus.COBOL.Runtime.CdataSectionHandler,
         MicroFocus.COBOL.Runtime.Win32,Version=4.0.0.0,Culture=neutral,
         PublicKeyToken=0412c5e0b2aaa8f0" />
        </sectionGroup>
    </configSections>
    <MicroFocus.COBOL.Tracing>
      <mftrace_config>
        <![CDATA[>
mftrace.dest                           = binfile
mftrace.emitter.binfile#location       = c:\logs
mftrace.level.mf.rts                   = info
mftrace.comp.mf.rts#pgm                = true
mftrace.comp.mf.rts#pgmload            = true
mftrace.comp.mf.rts#syspgm             = true
        <]]>
      </mftrace_config>
    </MicroFocus.COBOL.Tracing>
  </configuration>
Parent topic: Configuration File for CTF


Emitter List

The Consolidated Tracing Facility can output its trace information using any of the emitters listed below:

  • BINFILE Emitter Properties
    Set the BINFILE emitter properties to control the behavior and appearance of the binary trace file when viewed using the CTF Viewer.
  • TEXTFILE Emitter Properties
    Set the TEXTFILE emitter properties to control the behavior and appearance of the text trace file.
Parent topic: Introduction to the Consolidated Tracing Facility


BINFILE Emitter Properties

Set the BINFILE emitter properties to control the behavior and appearance of the binary trace file when viewed using the CTF Viewer.

The format of the trace files is platform independent, so you can use CTF Viewer to view binary trace files that were created on UNIX, for example.

To enable the BINFILE emitter, specify the following statement in the Consolidated Tracing Facility configuration file:

mftrace.dest = BINFILE

The following list shows the properties you can set to control the behavior of the BINFILE emitter:

Property | Description | Default
FILE The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
$(APPNAME)
The basename of the executable invoked to start the current process. For example, if run.exeis invoked, $(APPNAME) has the value "cobrun".
$(EMITTER)
Always "BINFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process
$(APPNAME).$(EMITTER).$(PID).ctb, or $(APPNAME).$(EMITTER).$(PID).ctb_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the BINFILE emitter is being used to output trace events for cobrun executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called cobrun.binfile.3456.ctb .
  • If the binfile emitter is being used to output trace events for myapp executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.binfile.1975.ctb_1, myapp.binfile.1975.ctb_2, and myapp.binfile.1975.ctb_3.
FLUSHEVERY | The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed. | 1
LOCATION The folder where the trace files are to be written. The folder specified by the MFTRACE_LOGS environment variable. If MFTRACE_LOGS is not set, the current folder is used.

If the folder specified by the LOCATION property does not exist, the Consolidated Tracing Facility tries to create it. If this fails, the Consolidated Tracing Facility uses the default location (as specified by the MFTRACE_LOGS environment variable). If this fails, the current folder is used.

MAXFILESIZE | The maximum amount of data (in Kb) that will be written to the trace file before the file is closed and the next trace file in the generation sequence is opened. The first trace file in a generation sequence results in the $(GEN) pseudo-variable (see the description of the FILE property, above) being set to 1, the second in the sequence results in it being set to 2, and so on until MAXGENERATION is exceeded. Once the MAXGENERATION number of files has been reached, the generation number reverts to 1 and the first trace file in the generation is overwritten. This is only used if MAXGENERATION > 1. | 0x00002800, indicating a maximum file size of 10 Mb.
MAXGENERATION | The maximum number of trace files that will be written to while tracing is enabled. Use this property in conjunction with the MAXFILESIZE property. | 1, indicating that only a single trace file will be created.
MultiProc | Controls whether trace events are written to the trace file by a single process or by multiple processes. If enabled for multiple processes, the File property must also be specified without the $(PID) pseudo-variable embedded in its name. | FALSE, indicating that the configured trace file includes only events from the current process
Parent topic: Emitter List
Related concepts
Example CTF Configuration Files
CTF Trace File Formats


TEXTFILE Emitter Properties

Set the TEXTFILE emitter properties to control the behavior and appearance of the text trace file.

A text trace file is the default format when a trace is run.

To control the behavior and the appearance of the file, set the following TEXTFILE emitter properties in the Consolidated Tracing Facility configuration file:

DELIMCHAR
The character used in the output file to delimit trace data parts for a trace event.
Default = space.
FILE
The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
$(APPNAME)
The basename of the executable invoked to start the current process. For example, "cobrun".
$(EMITTER)
Always "TEXTFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process.
Default = $(APPNAME).$(EMITTER).$(PID).log, or $(APPNAME).$(EMITTER).$(PID).log_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the TEXTFILE emitter is being used to output trace events for cobrun executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called cobrun.textfile.3456.log .
  • If the TEXTFILE emitter is being used to output trace events for myapp executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.textfile.1975.log_1, myapp.textfile.1975.log_2, and myapp.textfile.1975.log_3.
FLUSHEVERY
The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed.
Default = 1
FORMAT
The format to be used for each trace data record written to the file. You can use the following pseudo-variables in the format specification:
$(COMPONENT)
The name of the component outputting the trace event.
$(DATA)
The trace data specified by the component to be output for the trace event. Each trace part will be delimited by the character specified by the DELIMCHAR property.
$(DATE)
The current date, output as yyyy/mm /dd
$(EVENT)
The event identifier as specified by the component outputting the trace event.
$(LEVEL)
The tracing level:
  • 0: debug
  • 1: info
  • 2: warning
  • 3: error
  • 4: fatal
$(PID)
The current process identifier. Same as $(PROCESS).
$(PROCESS)
The current process identifier. Same as $(PID).
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
Default = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL) $(DATA)
HEXBLOCKSIZE
The number of hexadecimal bytes to be output in each block when outputting binary trace data. Each block of hexadecimal characters will be separated by a '-' character. For example, if HEXBLOCKSIZE is set to 4, and some binary trace data with the value 3132333435363738393A3B3C3D3E3F is specified for output, it would be formatted as follows:
31323334-35363738-393A3B3C-3D3E3F
LOCATION
The folder where the trace files are to be written, that is

If the folder specified by the LOCATION property does not exist, the Consolidated Tracing Facility tries to create it. If this fails, the Consolidated Tracing Facility uses the default location (as specified by the MFTRACE_LOGS environment variable). If this fails, the current folder is used.

Default = 8
MAXFILESIZE
The maximum amount of data (in Kb) that will be written to the trace file before the file is closed and the next trace file in the generation sequence is opened. The first trace file in a generation sequence results in the $(GEN) pseudo-variable (see the description of the FILE property, above) being set to 1, the second in the sequence results in it being set to 2, and so on until MAXGENERATION is exceeded. Once the MAXGENERATION number of files has been reached, the generation number reverts to 1 and the first trace file in the generation is overwritten. This is only used if MAXGENERATION > 1.
Default = 0x00002800, indicating a maximum file size of 10 Mb.
MAXGENERATION
The maximum number of trace files that will be written to while tracing is enabled. Use this property in conjunction with the MAXFILESIZE property.
Default = 1, indicating that only a single trace file will be created.
MultiProc
Controls whether trace events are written to the trace file by a single process or multiple processes. If enabled for multiple processes, the File property must also be specified without the $(PID) pseudo-variable embedded in its name.

Default=FALSE, indicating that the configured trace file includes only events from the current process.
QUOTESTRING
Whether or not string trace data is to be output enclosed in double-quote characters.
Default = TRUE
Parent topic: Emitter List
Related concepts
Example CTF Configuration Files
CTF Trace File Formats


Tracing Examples

By default, tracing is disabled for all components, so the absolute minimum you need to do to enable run-time system tracing is to specify an mftrace.level or mftrace.level.mf.rts entry in the configuration file. For example, if you have set the MFTRACE_CONFIG environment variable set as follows:

export MFTRACE_CONFIG=/home/mydir/ctf.cfg

and /home/mydir/ctf.cfg contains only the following entry:

mftrace.level=error

a trace file with an entry for event id 255 would be created by any process that generated a run-time system error. Note that you do not have to specify any properties for the mf.rts component for this event to be emitted; having the trace level set to error is enough.

In the examples that follow, the application mymain is used. This application comprises two programs: mymain.cbl and mysub.cbl that include the following code:

mymain.cbl:

 identification division.
 program-id. mymain.
 environment division.
 data division.
 working-storage section.
 01 my-var pic 9(9) external.
 procedure division.
     move 1 to my-var

     perform 5 times
         call 'mysub'
         add 1 to my-var
     end-perform

     cancel 'mysub'

     call 'myprog'
     goback.

mysub.cbl:

 identification division.
 program-id. mysub.
 environment division.
 data division.
 working-storage section.
 01 my-var pic 9(9) external.
 procedure division.
     display my-var
     goback.

When mymain is executed, run-time system error 173 (“Called program file not found in drive/directory”) occurs because of the call to myprog. The contents of a trace file generated using the configuration above look similar to the following:

1>   # -MFTRACE Text Emitter-
2>   # CommandLine      = mymain
3>   # ProcessId        = 442550
4>   # Date             = 2005/01/21
5>   # Time             = 11:19:44.498
6>   # Operating System = AIX 5.1
7>   # Computer Name    = asterix
8>   # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
9>   11:19:44.498 MF.RTS 255 3 173 1 "myprog"
The entries marked 1> through 8> are header records output by the TEXTFILE emitter giving information about the application being traced. 8> indicates the format of the subsequent trace entries (this example is using the default trace entry format), so the fields in entry 9> can be interpreted as follows:
Information in Trace File | Pseudo-variable | Description
11:19:44.498 | $(TIME) | The time the trace entry was output.
MF.RTS | $(COMPONENT) | The name of the component outputting the trace entry. MF.RTS indicates the run-time system.
255 | $(EVENT) | The event identifier. Event identifier 255 for the mf.rts component indicates a run-time system error.
3 $(LEVEL) The level of the error, based on the following values:
  • 0 = debug
  • 1 = info
  • 2 = warning
  • 3 = error
  • 4 = fatal
173 1 "myprog" | $(DATA) | Event-specific data.

If you now rerun mymain after changing the statement in the configuration file to specify a trace level of INFO, as follows:

mftrace.level=info

the trace file created contains entries for the run-time system initialization and de-initialization events in addition to the run-time system error event. The trace file looks similar to the following:

    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 1646624
    # Date             = 2005/01/21
    # Time             = 11:28:09.105
    # Operating System = AIX 5.1
    # Computer Name    = asterix
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    11:28:09.105 MF.RTS 128 1
    11:28:09.135 MF.RTS 129 1
    11:28:09.225 MF.RTS 255 3 173 1 "myprog"
    11:28:09.226 MF.RTS 130 1
    11:28:09.226 MF.RTS 131 1

To see which programs the application has invoked before the run-time system error occurred you need to set the PGM property. If you want to see where the programs have been loaded from and when they are canceled, you also need to set the PGMLOAD property, as follows:

mftrace.level=info
mftrace.comp.mf.rts#pgm=true
mftrace.comp.mf.rts#pgmload=true

When you rerun mymain, the trace file created contains additional entries for program load, entry, exit, and cancel events. The trace file looks similar to the following:

    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 1622058
    # Date             = 2005/01/21
    # Time             = 11:30:27.441
    # Operating System = AIX 5.1
    # Computer Name    = asterix
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    11:30:27.441 MF.RTS 128 1
    11:30:27.451 MF.RTS 129 1
    11:30:27.452 MF.RTS 19 1 0 0 "mymain" "" ""
    11:30:27.510 MF.RTS 6 1 17 0 "mymain"
    11:30:27.513 MF.RTS 19 1 0 0 "mysub" "gnt" "/home/myprogs"
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 20 1 0 0 "mysub"
1>  11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.515 MF.RTS 255 3 173 1 "myprog"
    11:30:27.515 MF.RTS 130 1
    11:30:27.515 MF.RTS 20 1 0 0 "mymain"
2>  11:30:27.515 MF.RTS 6 1 17 0 "mymain"
    11:30:27.515 MF.RTS 7 1
    11:30:27.516 MF.RTS 131 1

The entries marked 1> and 2> show event type 6 and 7 entries (program entry and exit) for a program immediately after an event type 20 entry (logical cancel) for the same program. This is because the Compiler embeds a cancel routine in all programs to close any files that the program may have opened. These cancel routines are implicitly invoked by the run-time system as part of a logical cancel operation.

To enable the tracing of all run-time system events with the exception of the memory management ones, you use the following configuration file entries:

mftrace.level = info
mftrace.comp.mf.rts#all=true
mftrace.comp.mf.rts#memory=false

When you rerun mymain, the trace file created contains additional entries for external data items. If you have compiled the programs with the AMODE directive, there would also be entries for each of the Mainframe Pointer Manager events. The trace file looks similar to the following:

    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 1073210
    # Date             = 2005/01/21
    # Time             = 11:33:52.015
    # Operating System = AIX 5.1
    # Computer Name    = asterix
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    11:33:52.015 MF.RTS 128 1
    11:33:52.031 MF.RTS 129 1
    11:33:52.032 MF.RTS 19 1 0 0 "mymain" "" ""
    11:33:52.090 MF.RTS 6 1 17 0 "mymain"
1>  11:33:52.091 MF.RTS 26 1 "my_var" 9
    11:33:52.093 MF.RTS 19 1 0 0 "mysub" "gnt" "/home/myprogs"
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 20 1 0 0 "mysub"
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.094 MF.RTS 7 1
    11:33:52.095 MF.RTS 255 3 173 1 "myprog"
    11:33:52.096 MF.RTS 130 1
    11:33:52.096 MF.RTS 20 1 0 0 "mymain"
    11:33:52.096 MF.RTS 6 1 17 0 "mymain"
    11:33:52.096 MF.RTS 7 1
    11:33:52.096 MF.RTS 41 1 0
    11:33:52.096 MF.RTS 41 1 1
2>  11:33:52.096 MF.RTS 27 1 "my_var"
    11:33:52.096 MF.RTS 131 1

The entries marked 1> and 2> show the additional entries for external data items.

Parent topic: Introduction to the Consolidated Tracing Facility
Related information
To enable CTF tracing


FaultFinder

FaultFinder is an aid to debugging production applications. It enables you to obtain a text-based report on the state of an application at the time of any abnormal application termination. The report is a snapshot of the application at the time of failure and identifies items such as open files, file buffers, loaded programs, and so on.

  • FaultFinder Tunables
    FaultFinder is controlled by tunables.
  • FaultFinder Report
    The FaultFinder report shows the state of an application at the time of any abnormal application termination
  • FaultFinder Listing Generator
    To help you analyze a FaultFinder report, you can take a snapshot of a program's source code, and its compiled characteristics, before shipping the program to your end-users.
Parent topic: Tools


FaultFinder Tunables

FaultFinder is controlled by tunables.

To turn on FaultFinder set the run-time tunable faultfind_level to a positive value. Then, if the application terminates abnormally, the run-time-system automatically invokes FaultFinder which in turn generates the report.

The following run-time tunables control the operation and output of FaultFinder:

faultfind_config=n Controls the inclusion of program memory data in the output file, where value indicates the action to perform and the type of memory as follows:

0 = Include all types of memory (default)

1 = Exclude working storage

2 = Exclude thread-local storage

4 = Exclude dynamically allocated memory

These values can be combined to suppress combinations of types of memory, for example, a value of 5 will exclude working storage and dynamically allocated memory.

faultfind_level=n | Turns on FaultFinder and enables tracing of events. n can be any positive value less than or equal to 1024 and enables the last n events to be dumped. The default value is 0.
faultfind_outfile="filename" The file to which the analysis is written. The default filename is fltfnd.out in the current working directory. If, for some reason, the specified file cannot be opened, output is directed to the screen.

You can specify the filename as follows:

"fault%option.log"

Where option can be:

d = replaced with the date of the fault in the format <yyyymmdd>

p = replaced with the process ID of the faulting process

t = replaced with the time of the fault in the format <hhmmss>

faultfind_recsize="record_size" | A numerecord_sizeric value, in bytes, that specifies the amount of extra data that is to be kept for each trace operation. record_size can be any non-negative value less than or equal to 1024. The default value is 64.

Example:

set faultfind_config=5
set faultfind_level=5
set faultfind_outfile="applflt.log"
set faultfind_recsize=1024

FaultFinder Performance

Enabling FaultFinder event tracing (that is, setting faultfind_level to a value greater than 0) does have a performance impact, although it should not be noticeable in most cases. The number of events traced does not significantly impact performance; tracing one event is not significantly faster than tracing 1000. The most expensive operations to trace are file operations; the worst case for FaultFinder is a file handling benchmark. Even if this is the case, you would expect no more than a 5% performance degradation. Most applications which perform a mixture of operations should see minimal impact on performance.

FaultFinder Listing Generator

To help you analyze a FaultFinder report, you can take a snapshot of a program's source code, and its compiled characteristics, before shipping the program to your end users. You can create a snapshot using the FaultFinder Listing Generator.

Parent topic: FaultFinder
Related information
FaultFinder Report
FaultFinder Listing Generator


FaultFinder Report

The FaultFinder report shows the state of an application at the time of any abnormal application termination

This information is contained in titled sections in the report. You can search for sections in the report by their titles.

For threaded programs (run with the multi-threading run-time system), additional information is output; this is discussed in the relevant sections.

Note:
  • On most systems only one process can have debug control over a target. If your target process is already being debugged by the Debugger, you might not be able to obtain a FaultFinder report.
  • It takes a finite amount of time to obtain the information used by FaultFinder. During this time, the target process is stopped and unable to respond to any user input.
  • FaultFinder Report - Environment
  • FaultFinder Report - Call Stack
  • FaultFinder Report - Loaded Programs
  • FaultFinder Report - Logically Canceled Programs
  • FaultFinder Report - Open Files
  • FaultFinder Report - Trace Back
Parent topic: FaultFinder
Related information
FaultFinder


FaultFinder Report - Environment

The Environment section of the report describes:

  • The application command line
  • The run-time system error (both number and message) that caused the problem
  • The date and time at which the dump was taken
  • For threaded applications, the identifier of the failing thread
  • The settings of all current environment variables
  • The settings of all the run-time tunables
Parent topic: FaultFinder Report


FaultFinder Report - Call Stack

The Call Stack section of the report contains, for each thread running at the time of failure, a call stack traceback. Programs are listed with full pathname and extension (where available). Entry points are not listed. The information for each thread is listed in a reverse calling hierarchy, so that:

  • The last program running (the program executing at time of termination) is listed first
  • Any programs that called the program that terminated, and any programs that called these programs are then listed
  • Finally, the initial program in the call hierarchy is listed

If the program contains Local-Storage and/or Linkage Sections, these sections are dumped with the corresponding call stack instance. For these sections, the following information is dumped:

  • Local-storage. The starting address is given followed by the contents. This information is dumped in hexadecimal and ASCII. Duplicate lines are not repeated but replaced by a single asterisk (*).
  • Linkage:
    • Addresses of Using parameters (in USING order)
    • Addresses of Linkage pointers (in Linkage Section order)

For .int files, the current program-counter is also dumped.

Parent topic: FaultFinder Report


FaultFinder Report - Loaded Programs

The Loaded Programs section of the report contains all currently loaded ("live") programs, with their reentrant and non-reentrant data areas. The non-reentrant data area has separate areas for working-storage and each instance of user-allocated data (using CBL_ALLOC_MEM, flag=0). A separate reentrant data area exists for each thread executing that program and has separate areas for thread-local storage and thread-local allocated data (using CBL_ALLOC_MEM, flag=8). Each chunk of data states the hexadecimal address of the data item and the dump (in hexadecimal and ASCII with duplicate lines not repeated but replaced by a single vertical bar (|)) of the data.

Note: The working-storage section includes all of the non-user program specific data areas, as in the file-control and file sections, as well as system needed non-reentrant space. To better define the start of the program's actual working-storage section, it is recommended that you insert a special data item as the first item in working-storage and give it a value that can easily be searched for.
Parent topic: FaultFinder Report


FaultFinder Report - Logically Canceled Programs

This section of the report contains a list of logically canceled programs, with full pathname and filename extensions.

Files that have been logically canceled are still known to the run-time system, so can be loaded and run directly without having to be loaded from disk. Files that are physically canceled release all their memory and no longer exist to the run-time system.

No other information is available in this section of the report.

Parent topic: FaultFinder Report


FaultFinder Report - Open Files

This section of the report contains information about all opened files, both local (non-external) and externally opened files. For each file the information listed is:

  • The filename
  • The exit status of a file operation
  • The record length
  • The organization
  • The open mode
  • For local files, which program it was opened by
  • The last record
  • The file control descriptor
  • The last operations performed on this file

The entire last record and the file control descriptor (FCD) are both dumped (with address) in hexadecimal and ASCII.

The operation trace records the basic operation (READ, WRITE, OPEN and so on) as well as the:

  • Exact operation code
  • Return status for that operation
  • Thread performing the operation
  • Dump of record data for the file operation

The last two items are only recorded when applicable.

Parent topic: FaultFinder Report


FaultFinder Report - Trace Back

The Trace Back section of the report lists the last n events for each thread, where n is defined by the run-time tunable faultfind_level. For each thread, the operations traced are:

  • CBL_ALLOC_MEM
  • CBL_ALLOC_DYN_MEM
  • CBL_ALLOC_SHMEM
  • CBL_ALLOC_THREAD_MEM
  • All file operations.

This section is broken down by thread; it records all operations for thread 1, followed by all operations recorded for thread 2, and so on. There are typically two events per operation: one as the operation begins, and another as it finishes.

Parent topic: FaultFinder Report


FaultFinder Listing Generator

To help you analyze a FaultFinder report, you can take a snapshot of a program's source code, and its compiled characteristics, before shipping the program to your end-users.
  • Using the FaultFinder Listing Generator
  • The FaultFinder Source Listing
Parent topic: FaultFinder


Using the FaultFinder Listing Generator

You can create a snapshot using the FaultFinder Listing Generator, which provides information in the form of a detailed listing file.

To create a listing file:

  1. Compile the program for debug
  2. Run the fflstcobfflst command

To run the FaultFinder Listing Generator, use the command:

cobfflst options filename [listfile]

where the parameters are:

options
Specifies the level of detail in the FaultFinder listing. options can be any combination of:

If you specify no options, the Listing Generator produces the full source, data map, procedure map and cross-reference listing. For details of these listings, see below.

s | Suppresses the source listing
d | Suppresses the data map listing
-p | Suppresses the procedure map listing
-x | Suppresses the cross reference listing
-ln | Specifies a page size of n lines. The default is 66 lines
-v | Verbose output with version information
filename
The name of the .idy file to be processed. You do not have to specify the .idy file extension as this is the default file type.
listfile
The name of the file to which the listing is saved. If you do not specify this parameter, the listing is directed to the screen.
Note: The FaultFinder Listing Generator always uses the .idy file, not the COBOL source file.

For example, if you have a program appsource.cbl, the following command generates a full listing minus any cross-reference information in the listing file appsource.ffl:

cobol appsource.cbl anim;

cobfflst -x appsource.idy appsource.ffl
Parent topic: FaultFinder Listing Generator


The FaultFinder Source Listing

The FaultFinder listing is composed of several parts.

The examples of output in the topics describing these parts were generated using the following program:

 program-id. 'funbar'.
 working-storage section.
 01 ws-var-1    pic x(255).

 thread-local-storage section.
 01 tls-var-1   pic x(1021).

 local-storage section.
 01 ls-var-1    pic x(511).

 linkage section.
 01 lnks-var-1  pic x(2011).
 01 lnks-var-1r pic a(1024) redefines lnks-var-1.
 01 lnks-var-2  pic x(3096).

 procedure division using lnks-var-1 lnks-var-2.
     move tls-var-1 to ws-var-1
     if ws-var-1 = lnks-var-1
         display ls-var-1
     end-if
     stop run.

This program was compiled to generated code, and the FaultFinder listing generated using the commands:

cob –x fun.cbl
cobfflst –l19 fun.idy fun.lst
  • FaultFinder Source Listing - Header
  • FaultFinder Source Listing - Source
  • FaultFinder Source Listing - Map
  • FaultFinder Source Listing - Xref
Parent topic: FaultFinder Listing Generator


FaultFinder Source Listing - Header

The header to the listing provides useful information on the compilation of the program. An example header appears below, with additional notes describing the information presented below:

* * * * * * * * * * * * * COMPILATION SUMMARY * * * * * * * * * * *

        Micro Focus Net Express        V1.1 revision 000

        Product ID   : HXCTG/AA0/00000
        Compiler ref : GNR-071060000AD

        Date compiled: 05-Oct-99
        Time Compiled: 18:20

        Source File: fun.cbl
        .idy File  : fun.id   y
        Program ID : funbar
        Compiled to: Gnt/object with xref information

- - - - - - - - - - - - - - - - Sizes  - - - - - - - - - - - - - - -

 INT Code Proc:   000059  Data: 0001C4  Local: 000200 Thread: 0003FE
 GNT Code User:   000178  Full:   0002C8

- - - - - - - - - - - - -  02 Linkage Item(s) - - - - - - - - - - - -

 LNKS-VAR-1                 :   2011 bytes (h"000007DB")
 LNKS-VAR-1R                :   1024 bytes (h"00000400") (redef)
 LNKS-VAR-2                 :   3096 bytes (h"00000C18")

- - - - - - - - - - - -  Key Compilation Directives - - - - - - - - -

 noP64 INTLEVEL(3) noREENTRANT  CHARSET(ASCII)
 MF    noOSVS      noVSC2       CHECKDIV        PERFORM-TYPE(MF)
 noBOUND         TRUNC(ANSI)
 noSPZERO        noIBMCOMP

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Information section

The first section of the listing provides information on the Compiler and the sources compiled. For the Compiler, the product name, product version, product ID and compiler reference number are given. These values are often useful to Micro Focus support representatives. For the source code, the files compiled, the resulting .idy file, the main entry point of the program and target mode of the compilation are given.

Sizes

The Sizes section of the report shows the sizes of the various segments defined in the program, in particular:

  • Intermediate code created during the syntax-check phase
  • Machine code generated during the generate phase
  • The Working-Storage Section, Local-Storage Section and the Thread-Local-Storage Section.

In the example listing above:

  • The syntax-check phase generated h"59" bytes of intermediate code
  • The generate phase created h"178" bytes of machine code as a result of user application code, and h"2C8" bytes of machine code in total
  • The Working-Storage Section is h"1C4" bytes long
  • The Local-Storage Section is h"200" bytes long
  • The Thread-Local-Storage Section is h"3FE" bytes long

Linkage items

The Linkage Item(s) section of the report lists the Linkage Section data items defined in this program, and their sizes. As these sizes are significant in interprogram communication, they warrant their own section. In the example above, the item LNKS-VAR-1R is a redefinition of LNKS-VAR-1, so there are effectively only two distinct linkage items.

Key Compilation Directives

The Key Compilation Directives section of the report lists the Compiler directives that affect run-time behavior.

Parent topic: The FaultFinder Source Listing


FaultFinder Source Listing - Source

There are two kinds of source listings that appear in the output, the Data Division listing and Procedure Division listing.

Data Division Listing

The Data Division listing looks like this:

fun.cbl, line 1
Line    Loc   :Size  ----+-*A-1-B--+----2----+----3----+----4----+---...-8
000001                        program-id. 'funbar'.
000002                        working-storage section.
000003  000050:0000FF         01 ws-var-1     pic x(255).
000004  000005                thread-local-storage section.
000006  000000:0003FD         01  tls-var-1   pic x(1021).
000007  000008                local-storage section.
000009  000000:0001FF         01  ls-var-1    pic x(511).
000010  000011                linkage section.
000012  000000:0007DB         01  lnks-var-1  pic x(2011).
000013  000000:000400         01  lnks-var-1r pic a(1024) redefines lnks-var-1.
000014  000000:000C18         01  lnks-var-2  pic x(3096).
000015  000016               procedure division using lnks-var-1 lnks-var-2.

The listing contains a page header, not shown in the example above, that gives product and compilation information. This is followed by the name of the source module that the first line of page originates from and its sequence number relative to that module. For example, the first line of page 1 in the example source listing originates from the module fun.cbl and is line 1 in that module.

After the line showing the module is a column scale; this indicates the COBOL areas of the source line (that is, Area A, Area B, and so on). In the example above, this scale is compressed to allow notations. In this scale line, there is also a header for the sequence line of the source lines being displayed.

Following the column scale is the Data Division code. The first 80 characters of each source line that was compiled are displayed in the body of the source listing. If a source line exceeds 80 characters, the excess characters are not shown.

The header indicates that the location (Loc) and size (Size) of each data item definition is displayed (in hexadecimal) immediately before the actual source line that defines the data item. For example, on line 3, the data item ws-var-1 is defined and it has an offset from the start of statically allocated data of h"50" and a size of h"ff" (decimal 255). Similarly, at line 6 the variable tls-var-1 has an offset of h"00" and a size of h"3FD" (decimal 1021).

Procedure Division Listing

The Procedure Division Listing looks like this:

fun.cbl, line 17
IntAddr:GntAddr----+-*A-1-B--+----2----+----3----+----4----+--- ... -8   Xref
000017  00002e                 sec1 section.                          =000017
000018  000030                 par1.                                  =000018
000019  000031:00000CC             move tls-var-1 to ws-var-1          000006 >000003
000020  000039:00000F4             if ws-var-1 = lnks-var-1           ?000003 ?000012
000021  000042:0000160                display ls-var-1                 000009
000022  000049                     end-if
000023  00004B:000016C         stop run.
000024

The listing contains a page header, not shown in the example above, that gives product and compilation information. This is followed by the name of the source module that the first line of the page originates from and its sequence number relative to that module. For example, the first line of page 2 in the listing originates from the module fun.cbl and is line 17.

After the line showing the module is a column scale that indicates the COBOL areas of the source line (that is, Area A, Area B, and so on). In the example listing above, this scale is compressed to allow notations. In the scale line there is also a header for the sequence line of the source lines being displayed.

The column scale contains the headers IntAddr and GntAddr, under which are shown the intermediate code address and the generated/object code address relative to the start of the module, of the actual source line from which the generated code was created. For example, for the syntax at line 19, the intermediate code address is h"31" and the generated/object code address is h"CC". The column scale aslo contains the header Xref, under which is shown the definition line of the data items that are manipulated in the statement, and any operations performed on the data items in the statement. The type of operations is indicated by a character:

= | Definition
> | Modification
? | Test

For example, on line 18 of the listing above, par1 is defined; on line 19, there is a reference to tls-var-1 which is defined on line 6 and there is a modification to ws-var-1 which is defined on line 3. On line 20, there is a test of ws-var-1, which is defined on line 3, and of lnks-var-1, which is defined on line 12.

Parent topic: The FaultFinder Source Listing


FaultFinder Source Listing - Map

There are two map listings, one for data items and one for procedural items.

Data Item Map Listing

The data item map listing looks like this:

* Data Map Listing
* Line   Name                           Addr   Size   Sec  Usage   Picture string
  000003 WS-VAR-1                       000050 0000FF WS   Alnum   PIC X(255)
  000006 TLS-VAR-1.                     000000 0003FD TS   Alnum   PIC X(1021)
  000009 LS-VAR-1                       000000 0001FF Lcl  Alnum   PIC X(511)
  000012 LNKS-VAR-1                     000000 0007DB Lnk  Alnum   PIC X(2011)
  000013 LNKS-VAR-1R.                   000000 000400 Lnk  Alpha   PIC A(1024)
  000014 LNKS-VAR-2                     000000 000C18 Lnk  Alnum   PIC X(3096)
  000000 RETURN-CODE                    000150 000002 WS   Comp    PIC S9(4) COMP
  000000 SORT-RETURN                    000154 000002 WS   Comp    PIC S9(4) COMP

This listing shows:

  • The line at which the data item was defined
  • The hexadecimal address and size of the data item
  • The section in which the data item was defined, identified by:
    WS | Working-Storage Section
    FS | File Section
    TS | Thread-Local Storage Section
    Lcl | Local Storage Section
    Lnk | Linkage Section
    Obj | Object-Storage Section
    SRg | Compiler Special Register
  • The usage defined for the data item, such as alphanumeric, alphabetic or computational
  • The picture of the data item

Procedural Item Map Listing

The procedural item map listing looks like this:

*  Procedure Map Listing
*  Line   Name                           Seg IntAddr  GntAddr  Sec/Par
   000017 SEC1                               000002E           Sec
   000018 PAR1
   0000030                                   00000CC           Par

This listing shows:

  • The line at which the procedural item was defined
  • The address in the intermediate and/or generated code at which the procedural item was defined
  • Whether the procedural item is a section or paragraph
Parent topic: The FaultFinder Source Listing


FaultFinder Source Listing - Xref

The Xref listing provides a sorted list of data names. It looks like this:

*  Xref Map Listing
*  Def'd  Name                    References, ?Tests, >Modifications
   000012 LNKS-VAR-1              0000013 0000016 ?0000020
   000013 LNKS-VAR-1R.
   000014 LNKS-VAR-2              0000016
   000009 LS-VAR-1                0000021
   000018 PAR1
   000017 SEC1
   000006 TLS-VAR-1               0000019
   000003 WS-VAR-1                >0000019 ?0000020
   000016 funbar*
   000001 funbar@

For each data item, the listing shows:

  • The line at which the data item was defined
  • The lines at which the data item is used
  • The operations performed on the data item on particular lines

The header to the third column, References, ?Tests, >Modifications, shows the type of operations that are recognized, and the indicators for these operations. For example, lnks-var-1 is defined at line 12, referenced at lines 13 and 16, and tested at line 20, while ws-var-1 is defined at line 3, modified at line 19 and tested at line 20.

A name suffixed with an asterisk (*) indicates the line at which that program's Procedure Division begins, while a name suffixed with the at sign (@) indicates the line at which that program's program id is defined.

Parent topic: The FaultFinder Source Listing


Profiler

  • Introduction to Profiler
  • Invoking Profiler
  • Profiler Output
  • Time Spent in Called Programs
  • Directives for Profiler
Parent topic: Tools


Introduction to Profiler

Note: This facility is supported in native COBOL only.

Profiler is a facility that enables you to obtain detailed statistics on the run-time performance of a COBOL program.

When you submit a COBOL source program to the Cob utility you can specify the PROFILE compiler directive. This causes the compiler to include code in your program that produces performance statistics about each paragraph of the program each time you run the compiled program. If your program contains no paragraphs, this report is not produced.

The performance statistics produced using the PROFILE compiler directive for that run of the program are contained in a file called program-name.ipf where program-name is the name of the program that was run. If an executable file is produced, then program-name is the first entry point name in the executable file.

These performance statistics are in compact form and first must be converted to a readable format, using Profiler.

By default, this file is created in the current working directory, but you can change this using the COBPRFDIR environment variable to specify an alternative directory. For example:

SET COBPRFDIR=/myipfdir

Profiler cannot be used on programs running multiple threads.

Parent topic: Profiler
Related information
PROFILE


Invoking Profiler

Note: This facility is supported in native COBOL only.

To start Profiler from the Visual COBOL command prompt, use the following command:

cobprof filenames directives

where the parameters are:

filenames
One or more files containing compact Profiler output. Profiler always searches for a file with the filename extension .ipf; if you specify any other extension, it is ignored.
directives
One or more of the directives that control the operation of Profiler. To specify a directive to Profiler, you must precede it with a plus sign (+). You can precede each directive with a plus sign; alternatively, you can specify one at the start of a list of directives.

Directives must be separated by one or more spaces. Where a Profiler directive takes a parameter, you can enclose the parameter either in quotation marks or in parentheses. If you use either of these, however, you must escape them using the backslash character ( \).

Profiler creates a file with the extension .prf, with the same basename as the .ipf file. If you profile more than one program at one time, Profiler output for all programs is appended to the output file for the first program, that is filename1 .prf.

Parent topic: Profiler


Profiler Output

When you run Profiler, the following banner is displayed:

* Micro Focus COBOL Profiler Vv.r
* name-1
.
.
.
* name-n

where name is one of the files listed in filenames in the command line.

For example, if you submit to the Cob utility the program prog1 with the PROFILE directive set, run the program, and then enter:

cobprof prog1 +LIST

the following output is produced on the console:

* Micro Focus COBOL Profiler Vv.r
* prog1
 Total time: 172 milliseconds. Module called once.

%time   time    entries  ms/entry    paragraph
-----------------------------------------------------------------
64.53   111     21       5           TEST-ROUTINE
17.44   30      1        30          PARA1
16.28   28      15       2           NAME-ENTRY
1.74    3       1        3           END-SECTION
0.00    0       1        0           INITIAL(UNNAMED) PARAGRAPH

The Profiler output gives the total execution time (in milliseconds) for the program run and then breaks this down for each section and paragraph in the program:

Output | Description
%time | Total percentage of execution time spent in the named section or paragraph
time | Total time (in milliseconds) spent in the named section or paragraph
entries | Number of times the named section or paragraph was entered
ms/entry | Average time (in milliseconds) per entry to the section or paragraph
paragraph | Section or paragraph to which performance statistics apply. The initial (unnamed) paragraph listed is the initialization code executed before the user part of the program is entered.

The product of the ms/entry and the number of entries should equal the total time spent in the section or paragraph; however, because all three values are truncated, there can be a slight discrepancy.

Parent topic: Profiler


Time Spent in Called Programs

How the run-time system treats the time spent in a called COBOL program that has been compiled with the PROFILE directive (a profiled program) depends on the value of the profile_behavior run-time tunable. You specify this tunable when you run the program that you want to be profiled.

If the profile_behavior run-time tunable is set to 0 (the default), then time spent in a profiled called program is recorded both in the called program and in the calling program.

If the profile_behavior run-time tunable is set to1, then time spent in a profiled called program is recorded only in the called program.

For example, suppose program prog_a calls program prog_c. prog_a is a profiled COBOL program. Then:

  • If prog_c is not COBOL, time spent in prog_c is recorded in prog_a
  • If prog_c is COBOL but is not profiled, time spent in prog_c is recorded in prog_a
  • If prog_c is COBOL and profiled, time spent in prog_c is recorded in prog_c, and not in prog_a

If prog_a actually calls prog_b, which calls prog_c, and prog_b is not a profiled COBOL program, then time in prog_b is always recorded in prog_a, while time in prog_c is recorded as explained above.

Parent topic: Profiler


Directives for Profiler

You can use the following directives to control the behavior of the COBOL Profiler.

ALL
Outputs a full performance profile. If you do not set the ALL directive, no statistics are produced for sections or paragraphs that are not entered or PERFORMed
ALPHA
Outputs performance statistics in alphabetical order by paragraph name. If you do not specify ALPHA, statistics are output in descending order of the total percentage time spent in each paragraph.
FORM"integer"
Specifies the page size in lines for the listing file. The minimum value you should specify is 6. The default size is 60 lines.
LIST["destination"]
Specifies where the listing is to be produced.
If destination is specified, the output is written to that file.
If destination is not specified, then the output is sent to the console, with page headings and page throws omitted. The VERBOSE Profiler directive is also set automatically.
If you do not set the LIST Profiler directive, then by default the output is produced in a file called filename.prf, where filename is the first name in the files listed on the command line.
[NO]VERBOSE
Displays on the screen messages output by Profiler. The default setting is NOVERBOSE, unless the LIST directive is set without a specified parameter, in which case VERBOSE is set automatically.
WIDE
Allows lines in the Profiler output to be up to 131 characters wide. If the WIDE directive is not set, lines are truncated to 79 characters.
Parent topic: Profiler
Related information
PROFILE


Rebuild

  • Overview
  • Command Line
  • Rebuild Options
  • Reorganizing Indexed Files
  • Rebuilding a Corrupt Indexed File
  • Converting a File
  • Validating an Indexed File
  • Rebuild through Fileshare
  • Callable Rebuild
  • Rebuild Examples
Parent topic: Tools


Overview

Rebuild is a file management utility invoked from the command prompt which enables you to:

  • Reorganize an indexed file
  • Rebuild a corrupt indexed file
  • Convert files from one organization to another
  • Validate an indexed file

The operation performed on a file by Rebuild depends on the options specified on the Rebuild command line.

Note:
  • If you are using Fileshare to access files, you should use only the Rebuild options that are supported for use through Fileshare. Otherwise, you will obtain undefined results.
  • When working with striped IDXFORMAT "8" files, you should ensure that:
    • All stripes are present
    • Rebuild picks up the File Handler configuration file extfh.cfg file.
    Failure to do this can lead to unpredictable results.
  • You should always take a backup copy of a file before you reorganize, rebuild or convert it. This is simply as a precaution against an incorrectly specified command line which could lead to file corruption. For indexed files, you should save both the index and data parts of the file.
  • Key offsets start at 1.
  • All temporary files are created in the system temporary file directory, unless you set TMPDIR to point to the directory where you would like to keep temporary files.
Parent topic: Rebuild
Related information
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Command Line

The format of the Rebuild command line is:

rebuild in-file [,out-file] [options]

Both in-file and out-file must include the filename extension. The filename of out-file must not be the same as in-file. You can use environment variables in place of in-file or out-file to implement filename mapping.

The options specified on the command line define the operation to be carried out by Rebuild.

  • Option Files
  • Redirection of Information
Parent topic: Rebuild
Related information
Overview
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Option Files

On the Rebuild command line, an at character (@) followed by a filename indicates that the named file contains Rebuild command line options.

If you use a file to supply Rebuild command line options, the file must be an ASCII text file.

Within the Rebuild options file:

  • Options should be separated by spaces.
  • Line ends are treated as spaces.
  • Any text between an asterisk (*) and the line end is treated as a comment.

In the following example:

rebuild infile.dat, outfile.dat @conv.par

conv.par is an ASCII text file containing Rebuild options.

Parent topic: Command Line
Related information
Redirection of Information


Redirection of Information

All information displayed by the Rebuild utility can be redirected to a text file using standard operating system redirection:

> | Creates a new file.
>> | Extends an existing file

For example:

rebuild oldms001.dat,ms001.dat -k:1+20<N> -i >> rebuild.prt

redirects the output from Rebuild to the existing file rebuild.prt.

Note: When you are redirecting output, do not use the -v option.
Parent topic: Command Line
Related information
Option Files


Rebuild Options

The processing performed by Rebuild is defined by the option(s) specified on the command line.

On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.

The following options are available:

-c | Specifies file compression
-d | Reconstructs an index from the data area of an indexed file
-e | Reports illegal duplicate keys and continues processing
-f | Validates indexed files
-i | Displays information about the files being processed
-k | Defines the key structure for an indexed file
-m | Reserved for future use
-n | Displays information about a file (no other processing is performed)
-o | Specifies the organization of the input and output files
-p | Rebuilds IDXFORMAT "8" file in place
-q | Reserved for future use
-r | Defines the record structure of the input and output files
-s | Specifies the format of the input file
-t | Specifies the format of the output file
-u | Attempts to recover a file for which the last update operation was not completed
-v | Displays a record count which is incremented as the file is processed
-y | Forces Rebuild to ignore file size discrepancies
-x | Specifies the order in which data is written when reorganizing an indexed file
-z | Instructs Rebuild to use a Fileshare server for file access
--q | Suppresses display of the Rebuild banner
--v | Displays the version number of Rebuild

Options can be placed in any order on the command line, except that options beginning with a double hyphen (--) must be placed before options beginning with a single hyphen (-). Options are free-format; spaces are required between options.

A colon (:) is required before parameters of the -f or -v options. For other options, a colon before parameters is optional. Do not insert spaces between the parameters of options.

Parent topic: Rebuild
Related information
Overview
Command Line
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Reorganizing Indexed Files

The format of the command line for reorganizing a file is:

rebuild in-file,out-file
[-c] [-d] [-i] [-k] [-n] [-p] [-s] [-v] [-x]

As indexed files are updated by adding, deleting and altering records, the index and data structures become disjointed, making processing less efficient. In addition, space left by deleted records is not always reused, making the file bigger than it needs to be.

After a large number of changes have been made, it is worth reorganizing an indexed file to rebuild the data and indices in an ordered sequential fashion and to reclaim any free space. This will ensure optimum performance and data integrity.

There are other reasons why you may want to reorganize a file. For example, if a file is processed sequentially, the access time to process the file increases over time, as the records start to become out of sequence due to updates. In this situation, you can reduce access time by reorganizing the file.

A third reason is to rebuild a duplicate key chain. A duplicate key has a duplicate occurrence value appended to it to make it unique. When a new duplicate key is added, the occurrence value of the last added key is incremented by one and used for the newly added key. If keys are deleted, no change is made to the occurrence values of the remaining keys. Therefore, you can reach the maximum number of duplicate values, even if some of those keys have already been deleted. In these circumstances it is a good idea to reorganize the file. For more information on duplicate keys, see the topic Duplicate Keysin the section File Organizations.

For example:

rebuild infile.dat,outfile.dat

causes Rebuild to read the data file (infile.dat) using the index file (infile.idx) and then create the output file (outfile.dat). The deleted records in infile.dat are not written to the output file.

Note: You cannot use the same filename for the input file and the output file.
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Rebuilding a Corrupt Indexed File

The format of the command line for rebuilding an index is:

rebuild in-file[,out-file]
[-c] [-d] [-e] [-i] [-k] [-n] [-p] [-s] [-v]

The out-file parameter is optional, but recommended, because if you do not specify it, and the Rebuild operation fails, you will lose your original file.

There are a number of reasons why an indexed file becomes corrupt, for example:

  • A close operation on an indexed file fails.
  • A power surge occurs while the indexed file is open.
  • The machine is rebooted or powered off while an indexed file is open.

When a COBOL program attempts to open a corrupt indexed file, the run-time system detects that the file is corrupt and returns an extended file status code.

Rebuild can recover corrupt indexed files for you:

  • If the data portion of the file is intact and only the index portion is corrupt, then Rebuild can generate a new index (.idx) file from the data file with no loss of data.
  • If the data portion of the file is corrupt then Rebuild can rebuild a complete new indexed file, both data and index portions, but there will be loss of data as Rebuild discards any corrupt data records that it encounters.
Note: When you use Rebuild to generate a new index file from an existing data file, the file can grow in size. One reason is that information held in the original index about free space in the data file is lost, which means that the free space cannot be reused. Another reason is that if you specify the -d option, index records are created individually as with normal I/O operations, leading to index nodes that are only partially filled. To overcome this problem, you should reorganize the file after you have rebuilt the index.

In the following example Rebuild reads the .idx file to get the key information, and creates a new index file, by reading the data file, infile.dat:

rebuild infile.dat

In the following example Rebuild reads the input file to get the key information, and creates a new indexed file, by working through the data in physical order, skipping over duplicate records:

rebuild infile.dat, outfile.dat -d -e

If the index file is not present, you must supply information about the key structure using the -k option.

Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Converting a File

The format of the command line for converting a file is:

rebuild in-file,out-file [-c] [-i]
    [-k] [-o] [-r] [-s] [-t] [-v]

Rebuild enables you to convert files from one file organization and format to another.

In the following example Rebuild converts a C-ISAM file into the format used by this system and compresses the data part of the file:

rebuild infile.dat,outfile.dat -s:c-isam -c:d1 -t:mf
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Validating an Indexed File

The format of the command line for validating an indexed file is:

rebuild in-file -f

Rebuild can perform a number of validation checks and you can request all of them, or just a subset of them. Of course, the more checks you request, the longer the validation process takes.

In the following example Rebuild performs a full integrity check on the file:

rebuild test.dat -f
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Rebuild through Fileshare

You can use Rebuild on files that reside on Fileshare servers, but only with a limited range of Rebuild options. The format of the command line for using Rebuild through Fileshare is:

rebuild in-file[,out-file] -z:server-name {/l|/n}

where:

server-name The name of a Fileshare server. All occurrences of server-name must refer to the same Fileshare server.

You can also specify a Fileshare server without using the -z Rebuild option. The format of the command line for this is:

rebuild $$server-name/in-file [$$server-name/out-file] {/l|/n}

On UNIX systems, replace the server-name prefix $$ with \$\$.

Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Callable Rebuild
Rebuild Examples


Callable Rebuild

You can call Rebuild from your COBOL program as follows:

call "callrb" using commands status

where the parameters are:

commands | A PIC X(600) item containing the Rebuild command line. This item must be 600 bytes in length because Rebuild scans the command line backwards from offset 599.
status | A PIC XX COMP X item containing the returned file status. This item shows the result of the call to Rebuild.

When called from within a program, Rebuild does not display any of its usual messages.

If an error occurs or the rebuild is unsuccessful, RETURN-CODE contains a non-zero value and status contains the returned file status. You should always check RETURN-CODE and status after a call to Rebuild.

The possible values of RETURN-CODE are shown below.

Value | Description
0 | Rebuild executed successfully
1 | An error occurred on the input file such as file not found or invalid file format - check status parameter
2 | An error occurred on the output file - check status parameter
3 | Error in sort
4 | File is corrupt
5 | Attempt to do a /k:a:exists
6 | Attempt to do a /k:r:onprime
7 | Attempt to do a /k:r:dontexist
8 | Too many duplicates on out
9 | The parameter list contained an error such as an invalid option or an invalid combination of options

If an error occurs, execute Rebuild from the command line on the same file with a set of identical options. The screen output should give a more precise indication as to the cause of the error.

Note: If you are using the -f option (validate an indexed file), then any non-zero RETURN-CODE indicates that the file is corrupt. Again, execute Rebuild from the command line on the same file with a set of identical options to obtain more precise information.

The following example shows Rebuild being called from within a COBOL program.

 01 parameters   pic x(600).
 01 status       pic xx comp-x.
   ...
     move "infile.dat,outfile.dat -s:lii -c:d1" to parameters
     call "callrb" using parameters,status
     end-call
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Rebuild Examples


Rebuild Examples

The section provides examples of using Rebuild.

rebuild infile.dat,outfile.dat -i

Reorganizes the file. The data is written in the order of the prime record key, and processing information displayed when the reorganization is complete.

rebuild infile.dat,outfile.dat -x:3

Reorganizes the file. The data is written in the order of the third alternate key.

rebuild infile.dat

Rebuilds the indexed file (assuming that the index (.idx) file is still present, and the key information held therein is not corrupt).

rebuild infile.dat -k:1+20 -i

Rebuilds the indexed file. The index (.idx) file does not need to exist, and is ignored if it does. It will be completely recreated using the key definition specified (which need not correspond to the key definition used when the file was created). Processing information will be displayed when the rebuild is complete.

With C-ISAM and Level 2 files that do not have index files, use the -r and -s options to specify the record information and file format.

rebuild infile.dat,outfile.dat -s:c-isam -c:d1 -t:mf

Converts a C-ISAM format index file into the format used by this system and compresses the data part of the file.

rebuild infile.dat,outfile.dat --o:rel,ind -k:1+2:3+10d
-c:i7 -r:f10

Generates an index, with key compression, for a fixed-length relative file.

rebuild infile.dat,outfile.dat -s:lii -t:lii

Reorganizes a LEVEL II V2.5 COBOL format file and retains the LII structure on the output file. It is possible to combine -s and -t with other formats in a similar manner.

set data=/tmp.dat rebuild data -i

Reorganizes and displays information about the file /tmp.dat.

Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild


Configuring CCI

  • Configuring CCI Introduction
  • CCITCP Configuration
    CCITCP is supported on Windows 95, Windows 98 and Windows NT and UNIX systems.
  • CCINAMPU Configuration
    CCINAMPU is supported on UNIX systems only.
  • CCI Trace
    CCI Trace enables you to trace any CCI function calls made by applications. The information obtained from the trace is sent to a log file. By default this is called ccitrc1.trc, which a matching index file ccitrc1.idx. In addition to the trace information, data flow information can be sent to a separate set of log files with the default names ccitrc1d.trc and ccitrc1d.idx, depending on the trace options specified.Although the trace log file is not generally in a readable format, any data output from the CCI data buffers will not be encrypted when written to a trace file. Applications that use CCI can be coded to block data tracing for security reasons.
  • CCI.INI - The CCI Configuration File
  • CCI Status Messages
Parent topic: Micro Focus COBOL Server for UNIX


Configuring CCI Introduction

CCI is the acronym for Common Communications Interface. CCI is the technology used by Micro Focus products such as Mainframe Access, Fileshare and CICS, to enable communications applications. CCI allows a common approach to configuration and diagnosis of errors for users of Micro Focus distributed applications.

This book provides a wide range of examples for configuring the various Micro Focus products that use CCI. All of this information is applicable to all products that make use of CCI technology. The information is divided into several categories:

  • Specific information regarding each communications protocol supported
  • Application configuration information
  • Tracing and CCI.INI file entry specifics used to customize your communications application
  • Error messages and their possible resolution.

UNIX: If you are using CCI on UNIX, you can ignore the chapters about CCIAPPC, CCIIPX, CCINETB and CCI Trace, and all of the appendices.

Windows: If you are using CCI on Windows, you can ignore the chapter on CCINAMPU.

Parent topic: Configuring CCI
Related information
CCITCP Configuration
CCINAMPU Configuration
CCI Trace
CCI.INI - The CCI Configuration File
CCI Status Messages


CCITCP Configuration

  • CCI Support For TCP/IP
  • Advanced Features
  • Application Configuration
Parent topic: Configuring CCI
Related information
Configuring CCI Introduction
CCINAMPU Configuration
CCI Trace
CCI.INI - The CCI Configuration File
CCI Status Messages


CCI Support For TCP/IP

CCI over TCP/IP (CCITCP) allows an application to connect to another application (on another machine, usually, although it can be another process on the same machine) in two ways: directly, by specifying the TCP/IP address and port being used by the application you want to connect to (this is described in the Advanced Features section); or indirectly, by specifying a logical "Server Name" of the service you wish to connect to.

This second method allows the most flexibility: the applications can be moved from machine to machine without being altered; and the details of the machine they are running on are unimportant (as long as they support CCI and TCP/IP, of course). This flexibility is achieved by having an intermediate program which CCI can query when a connection request is made. This program contains or can obtain the necessary details to allow an application to establish a connection with another application of a given Server Name. This program is called the CCITCP2 registration daemon.

Before using CCI over TCP/IP (with or without using CCITCP2) there is some configuration that is necessary, described in the sections below.

  • CCI Support Modules for TCP/IP
  • TCP/IP Configuration
  • Running the CCI Configuration Utility
  • CCI Configuration for UNIX Users
  • Using CCITCP2
Parent topic: CCITCP Configuration
Related information
Advanced Features


CCI Support Modules for TCP/IP

In order to enable CCI support for TCP/IP three executable modules are provided:

  • CCITC32.DLL(cobtcp.so on UNIX systems) - which enables the CCI interface routines necessary for CCI equipped machines to communicate with each other. The module, its interface, and its associated functionality and other support modules, is generically referred to as CCITCP. Micro Focus products use this (and other protocol-specific CCI modules) so that they do not need to worry about the complexities of the underlying network protocol.
  • CCITCP2.EXE(ccitcp2 on UNIX systems) - a server registration module, which is used to register and advertise CCI server processes that are available for CCI clients to call. It is designed to be run as a background application, and so is sometimes referred to as a "daemon" process.
  • CCIINST.EXE(not supplied on UNIX systems) - adds necessary entries to the TCP/IP services file automatically and registers the name of the machine which CCI clients will use to connect to a CCITCP2 process. It generally needs to be run only once on a machine.
Parent topic: CCI Support For TCP/IP


TCP/IP Configuration

Before the CCI modules can work effectively the appropriate TCP/IP network hardware and software drivers must be already installed, fully configured, and working. Once the TCP/IP software is installed and configured, the network connections should be fully checked out using suitable utilities, such as the TCP/IP standard commands "ping" and "ftp", before attempting to use CCI over TCP/IP. Ensure that if hostnames are going to be used (as opposed to only dotted decimal IP addresses) that the Domain Name Server (DNS) configuration is correct and that the service is working.

Where a network is connected to other networks, ensure that TCP/IP is aware of the gateway(s) to these networks by running "route add" or a similar command. Please see your TCP/IP vendor's installation and configuration guides for details of these steps.

Once you are certain that TCP/IP is fully configured and functional and that the machines which you wish to communicate with are similarly set up and reachable, then the only other configuration issue that needs to be resolved is where (and whether) a CCITCP2 daemon will be run to enable these machines to contact each other.

Parent topic: CCI Support For TCP/IP


Running the CCI Configuration Utility

This section does not apply to UNIX installations. Please refer to CCI Configuration for UNIX users

If a CCITCP2 daemon is used to allow CCITCP clients and servers to establish contact then the "CCI Configuration" utility needs to be run first. It can be started by going to the "Configuration" group under the product Start menu item and selecting "CCI Configuration". Alternatively just run CCIINST from any Micro Focus Command Prompt.

The CCI Configuration Utility asks for the address of the machine in the reachable network which is running a CCITCP2 daemon. You can enter either a hostname or a dotted decimal format address. If you do not know the TCP/IP hostname or address of the system that the CCITCP2 daemon is running on, contact your system/network administrator.

The CCI Configuration Utility also updates the TCP/IP services file with values necessary for CCI to work over TCP/IP.

If you leave the hostname field empty, CCI assumes that the CCITCP2 daemon will be running on the local machine, and the changes to the services file are still made.

If the machine running the CCITCP2 daemon changes, you must rerun the CCI Installation Utility and change the hostname to the new value. If there are any Micro Focus processes running which were started before the value was changed (e.g. Command Prompt, Integrated Development Environment, etc.) then these will need to be re-started before they pick up the new value.

Parent topic: CCI Support For TCP/IP
Related information
CCI Configuration for UNIX users


CCI Configuration for UNIX Users

Prior to using CCITCP with CCITCP2, an entry must be made in the /etc/services file as follows:-

mfcobol 86/udp

Without this entry in the /etc/services file, CCITCP2 cannot function.

On UNIX systems the user is required to set an environment variable "CCITCP2" to select the location of the machine hosting CCITCP2 executable in the network that is being used.

An example of the setting of a CCITCP2 environment variable for korn shell users is

export CCITCP2=myhostmachinename

or

export CCITCP2=192.77.293.1

The method for setting environment variables in other UNIX shells differs slightly from the examples given here, please use the appropriate method for the user shell of your choice.

Please refer to the section Environment Variables and the CCI.INI File for more details of the advanced configuration of CCITCP.

Parent topic: CCI Support For TCP/IP
Related information
Environment Variables and the CCI.INI File


Using CCITCP2

There only needs to be one CCITCP2 process active on a network in order for CCI over TCP/IP to work, as long as all machines have been configured (using the CCI Configuration Utility) to use it. Alternatively, multiple CCITCP2 processes running in the network can coexist and can communicate between each other so that a machine configured to use one daemon can find an application registered with a different daemon in the network. For instance, it is possible for every machine on the network to be running a copy of CCITCP2 and be configured to use their own local copy to search for connections. This would, however, generate a lot more network broadcast traffic compared to having just one daemon which all machines are configured to use.

The CCI Configuration Utility needs to be run on a machine before CCITCP2 can be successfully started on it (enter a blank hostname if the daemon is run locally). Once started, the daemon will accept service registrations until the effective RAM available to the process is exhausted, or until it is shut down.

CCITCP2 can be started manually at any time (as long as it is not already running) by entering:

ccitcp2

at a Micro Focus command prompt, or it can be started automatically at system start-up by including it in the startup folder. Alternatively, on NT, it can be installed as a service (see CCITCP2 as an NT Service).

On UNIX systems CCITCP2 can only be started by a superuser (root).

  • Using Directory Server Instead of CCITCP2
  • CCITCP2 Search Order
  • CCITCP2 Troubleshooting
Parent topic: CCI Support For TCP/IP
Related information
CCI Configuration Utility
CCITCP2 as an NT Service


Using Directory Server Instead of CCITCP2

If you have installed COBOL Server, available with Visual COBOL and standalone, then the CCITCP2 program will have been replaced by a trigger program that calls the Micro Focus Directory Server program. As far as CCI users are concerned, the Directory Server serves the same purpose as CCITCP2 and behaves in exactly the same way. Each machine that runs COBOL Server must have the Directory Server program running on it, and for Windows machines it is automatically installed and started as a service. For more information about the Directory Server see your Enterprise Server Configuration and Administration book.

Parent topic: Using CCITCP2


CCITCP2 Search Order

If both the Server Name and Machine Name (see Application Configuration for a definition of these terms) are specified by the client application, the CCITCP2 process returns the machine and port address of the service specified to the client so that it can establish a connection with the named service. If the service is not found, an error is returned.

However, if the Server Name is specified but the Machine Name is not, the CCITCP2 process searches all the registered Server Names in the reachable network in the following order until either the named service is found or an error is returned:

  1. The CCITCP2 process returns the address and port of any occurrence of the Server Name that is registered with it and is running on the same machine as the CCITCP2 process.
  2. The CCITCP2 process returns the address and port of any occurrence of the named service that is registered with it but is running on another machine.
  3. The CCITCP2 process returns the address and port of the first occurrence of the named service that is registered with any other addressable CCITCP2 process. Note that there is no guarantee which particular service this will be.
  4. The CCITCP2 process returns an error to the calling program if the named service still cannot be found. At this point the client will probably keep re-trying for a fixed amount of time, in case the service has been started after the client first began searching for it.

You can avoid the potential problem of producing an undesired connection from the third level search by closely observing the rules followed at the first two search levels or by using a unique name for each server process on the network.

Parent topic: Using CCITCP2
Related information
Application Configuration


CCITCP2 Troubleshooting

This section provides information that may be useful if you experience problems when using CCI over TCP/IP with CCITCP2.

  • "mfcobol port entry not found in services file" error

    Run the CCI Configuration Utility on the machine receiving this error: this should automatically update the TCP/IP services file with the necessary entries.

  • "Cannot find CCITCP2" error

    Run the CCI Configuration Utility on the machine receiving this error. Make sure that the hostname or TCP address value matches that of the machine running the CCITCP2 process you expect to use, and that the CCITCP2 process is running on that machine. Use "ping" and "ftp" to make sure that the machine is reachable using the address you have specified. Check that there are no CCITCP environment variables or CCI.INI file entries over-riding the value specified by the Configuration Utility. If the value has been changed recently, make sure that the failing process has been subsequently re-started.

  • "Registered service found but could not make a connection" error

    There are two main possible causes of this message:

    • This error can occur if the CCI server the client is trying to connect to has abnormally terminated, but still remains registered with the CCITCP daemon that both the client and server are pointed at. (Where possible, CCITCP attempts to detect this sort of abnormal termination and tries to remove the Server Name entry which is no longer valid, however this cannot be guaranteed.) The client then connects to the CCITCP2 daemon, which tells it where to look for the CCI server, but when it then tries to connect to the terminated server and fails it will give the above error.

      To check to see if this is what is happening close and re-start the CCITCP2 daemon that the client is pointed at. This will clear it of all registered Server Names, including any "orphan" servers. (If CCITCP2 is running in debug console mode then you can press F2 and it will list what CCI servers are registered with it.) Check to see that the CCI service is not abnormally terminating.

    • Another reason you may get this error is if both the CCI server and client can see the CCITCP2 daemon, but they cannot contact each other directly (because of the network topology: packets from the client are not reaching the server because a bridge or router is not allowing them through). Check that the client can "ftp" from the machine running the CCI server and visa versa. If they cannot, then notify the system administrator.
  • "A CCITCP call has timed out" error

    This most commonly occurs if the server application that the client is attempting to contact is not running at the time the client is started. However, it can also a be produced in a network topology which includes routers or bridges which have not been configured to allow CCITCP2 daemons to communicate with each other. For example, if a client fails to connect with a registered service as follows:

    • Server A registers itself with the CCITCP2 process running on machine A
    • Client B looks for server A using the CCITCP2 process running on machine B
    • Client B fails to connect to server A.

    The CCITCP2 modules are designed to communicate with each other using the TCP/IP broadcast address mechanism. If this is not correctly configured, CCITCP2 cannot locate services registered with other CCITCP2 modules. If this happens, you should advise your system administrator.

    System administrators should be aware of the following:

    • Bridges and gateways that are not configured to pass broadcast addressed packets will have a blocking effect on CCITCP connectivity. These items must be re-configured to pass broadcast packets if the registration of processes is performed on a leg of a network other than that of the requesting client. The actual configuration operations for these are specific to each device. In this situation, the use of a CCITCP2 module on the same leg of the network for both client and server applications will avoid the problem.
    • Most bridges and routers can be configured to only pass broadcast packets using certain TCP/IP port numbers; that is, a filter is applied. To allow CCITCP2 to communicate across bridged networks, your router or bridge should allow broadcasts using port number 86 in the UDP domain to pass unhindered through the filter.

    For CCITCP2 modules to communicate correctly, your network must be configured to pass broadcast packets to all areas that want to use CCITCP.

Parent topic: Using CCITCP2
Related information
CCI Configuration Utility


Advanced Features

  • Running CCITCP2 as an NT Service
  • Using CCI Over TCP/IP Without CCITCP2
Parent topic: CCITCP Configuration


Running CCITCP2 as an NT Service

On Windows NT you can run the CCITCP2 daemon as an NT service by entering:

ccitcp2 -i

at the Micro Focus command prompt. (You must be logged on as a user with Administrator privilege to do this.)

Once installed as an NT service, CCITCP2 can be started and stopped via the Control Panel in the usual way.

You can use the -c option to install CCITCP2 as a service and run it in debug mode so that a console shows services being registered and connections being made:

ccitcp2 -c

Note that if CCITCP has already been installed as a non-console service it will need to be uninstalled first. To uninstall CCITCP2 as a service, use the -u option:

ccitcp2 -u

The -? option lists the available CCITCP2 startup modes.

Note:

If CCITCP2 is installed as an NT service, it will be started automatically when the NT system is re-started. If a non-service CCITCP2 has previously been added to the Windows Startup group, it should be removed; otherwise, Windows will try to start a second instance of CCITCP2.

If CCITCP2 is started from a command line with the -d (debug) option or installed as a service with the -c option, then pressing the F2 key will list the CCI services that are registered with the daemon. F4 toggles the echoing of the console output to the ccitcp2.log file in the current directory of the daemon.

Note:

If you have installed Micro Focus Enterprise Server for Windows, available with Net Express and also standalone, then the Micro Focus Directory Server (MFDS) will have been installed as a service, so there is no need to manually install CCITCP2 as a service. (If you have already installed CCITCP2 as a service, stop it and uninstall it before installing Micro Focus Enterprise Server for Windows.) For more information see the section Using Directory Server Instead of CCITCP2.

Parent topic: Advanced Features
Related information
Using Directory Server Instead of CCITCP2


Using CCI Over TCP/IP Without CCITCP2

  • Direct Connection and Starting Servers on Fixed Ports
  • Environment Variables and the CCI.INI File
Parent topic: Advanced Features


Direct Connection and Starting Servers on Fixed Ports

A CCITCP2 registration daemon is not necessary if the CCI client application and the CCI server application establish a connection directly between each other. This can only be done when the server application starts up on a specific TCP port, and the client knows which address and port the server is using.

In a relatively static application enterprise environment where the server application location is well-defined and persistent, then using direct connection can have advantages over using a CCITCP2 registration process to help establish a connection.

Allowing a server application to listen on a known, fixed port means that clients can contact the server through a security firewall if a gap has been configured for that port and address.

A CCI server can support both direct connection and normal connection via a CCITCP2 daemon simultaneously. If a server starts on a fixed port, and a CCITCP2 daemon is present, then it will register a Server Name with it as normal, but in addition clients will be able to connect to it directly because the port it is using is known. If the CCITCP2 daemon is not present or reachable then a fixed port server will still start successfully, but only clients who attempt to connect directly will be able to contact it.

Parent topic: Using CCI Over TCP/IP Without CCITCP2


Environment Variables and the CCI.INI File

A variety of environment variables and CCI.INI file entries can be used to customize CCI behavior either on a machine-wide or per-process basis. Most users should not need to use either of these methods, but they are provided in case a greater degree of application control is required.

If more than one of the above methods is used for the same purpose or feature, the order of precedence that determines the behavior is:

  1. environment variable
  2. CCI.INI option
  3. the original or default behavior
  • CCITCP Environment Variables
  • CCITCP Options in the CCI.INI File
Parent topic: Using CCI Over TCP/IP Without CCITCP2


CCITCP Environment Variables

In the following sections UNIX users should use the appropriate method of setting environment variables for the user shell which is being used. The examples given are guides using the manner of setting environment variables found on the PC.

  • CCITCP2 Environment Variable

    Instead of using the CCI Configuration Utility to set the TCP address of the machine running the CCITCP2 registration daemon the environment variable "CCITCP2" can be used instead. This may be useful if you need different processes on the same machine to contact different registration daemons. The value can be set from the command prompt by typing:

    set CCITCP2=hostname

    where hostname is the TCP hostname or dotted decimal IP address of the machine running the CCITCP2 daemon you wish to contact from that session.

    The environment variable value will always take precedence over any value set using the Configuration Utility. To restore a process to using the value set by the Configuration Utility simply set the environment variable to an empty string e.g.

    set CCITCP2=

    Alternatively, if this environment variable is set system-wide (by creating a system variable in the system environment settings, or by using a CONFIG.SYS file) then this value will always take precedence over any value set using the Configuration Utility.

  • CCITCPS_ Environment Variable

    If you want to start a CCI server on a fixed port, then you can associate the Server Name with the port value by using the CCITCPS_ environment variable (instead of appending the information on the Server Name itself, as described in the CCITCP Server Name section). If the Server Name is server_name, and you want it to use the fixed TCP port 3000, this can be specified by typing:

    set CCITCPS_server_name=MFPORT:3000

    Note that this will only work if the server application process is started in the same session or process that has this environment variable set.

  • CCITCPT_ Environment Variable

    If a client is known to be trying to connect to a server with Server Name server_name, and the TCP address (server_hostname) and port (e.g. 3000) that the server is using is known, then the client can be made to connect directly to it by setting an environment variable as follows:

    CCITCPT_server_name=MFNODE:server_hostname,MFPORT:3000

    Note that this can be used instead of setting the client Machine Name value (see section CCITCP Machine Name). This is useful if the Machine Name value the client specifies cannot be altered by an application defined method.

Parent topic: Environment Variables and the CCI.INI File
Related information
CCITCP Server Name
CCITCP Machine Name


CCITCP Options in the CCI.INI File

The CCI.INI file is only used by CCITCP if direct connection or a fixed port server is required. In addition, this configuration method is only recommended when the Server Name or Machine Name cannot be modified by the application that is using CCI, and the environment variable method described in the section above is also not considered suitable.

There are two possible sections in the CCI.INI file which are specifically used by CCITCP:

[ccitcp-servers]

which can have entries of the following form:

server_name=MFPORT:xxxxx

This is used exclusively to match a given Server Name server_name (see CCITCP Server Name for a description of valid values) with a fixed TCP port value xxxxxx.

The other CCI.INI section used is:

[ccitcp-targets]

which expects entries of the following form:

server_name=MFNODE:server_hostname,MFPORT:xxxxx

This is used exclusively by clients to associate a target Server Name server_name with a Machine Name value to the right of the "=" character (see CCITCP Machine Name for valid values and uses).

Parent topic: Environment Variables and the CCI.INI File
Related information
CCITCP Server Name
CCITCP Machine Name


Application Configuration

CCITCP Client/Server applications use the CCI Server Name and Machine Name parameters to enable the CCI Client to specify the CCI Server with which to communicate.

The CCI Server identifies itself on the network by using the Server Name parameter. The CCI Client specifies the CCI Server using the Server Name. Additionally, if it only wants to find this Server running on a particular machine in the network, it needs to specify the Machine Name parameter.

  • CCITCP Server Name
  • CCITCP Machine Name
Parent topic: CCITCP Configuration


CCITCP Server Name

Both CCI server and CCI client applications need to have a Server Name specified: server applications need to register themselves as available under this name (or what fixed port to use); and clients need to specify which server they wish to contact. The Server Name is not the same as the TCP host name of the machine the application is running on, but a name chosen by the server application to identify itself on the network so that client applications can find it whichever machine it is running on.

Server Name can be any valid alphanumeric string (up to 127 characters in length). Names beginning with a ',' character, or including the consecutive characters ",MF" are reserved for Micro Focus use.

If you wish to have the server start on a fixed or known TCP port (see Direct Connection and Starting Servers on Fixed Ports), then this can be achieved by appending the string ",MFPORT:xxxxx" to the Server Name, where xxxxx is the decimal value of the port. This string is not used as part of the Server Name, but is interpreted by CCI so that the server uses the specified port for listening for incoming clients. If you do not wish the server to have any name (that is, clients cannot use CCITCP2 to contact the server, but can only specify it directly by using the Machine Name parameter) then the Server Name need only consist of this string.

Note:

It is recommended that you do not use port numbers below 2000 as these may already be in use by standard TCP services. The maximum port value normally supported is 65535. Care should be taken not to use a port value that is already in use by other standard applications: check with the system or network administrator on valid port value ranges that should be used.

Parent topic: Application Configuration
Related information
Direct Connection and Starting Servers on Fixed Ports


CCITCP Machine Name

This is a parameter that only needs to be specified by CCI client applications.

This should be the TCP address (either the hostname if DNS is enabled, or the dotted decimal address if not) of the machine you wish to restrict the client to contacting. If you know that the Server Name of the application the client is trying to contact is unique in the reachable network, or you do not care which server of this same name it connects to, then this parameter is optional.

If you do not wish to use a CCITCP2 daemon to resolve the TCP address and port that the server is using (see Using CCI over TCP/IP without CCITCP2), but want the client to contact the server directly, then the Machine Name must have the following form:

MFNODE:server_hostname,MFPORT:xxxxx

where server_hostname is the hostname or dotted decimal address which the server application is using, and xxxxxx is the decimal port value.

Parent topic: Application Configuration
Related information
Using CCI over TCP/IP without CCITCP2


CCINAMPU Configuration

  • CCI Support for UNIX Named Pipes (FIFOs)
  • Application Configuration
Parent topic: Configuring CCI
Related information
Configuring CCI Introduction
CCITCP Configuration
CCI Trace
CCI.INI - The CCI Configuration File
CCI Status Messages


CCI Support for UNIX Named Pipes (FIFOs)

  • CCI Support Module for UNIX Named Pipes
  • Transport Speed
  • CCI.INI File Options for CCINAMPU
Parent topic: CCINAMPU Configuration


CCI Support Module for UNIX Named Pipes

In order to enable CCI support for UNIX Named Pipes, one shared object executable module is supplied

  • cobnampu.so - which enables the CCI interface routines in CCI enabled processes to communicate with each other.

The CCINAMPU module is used to connect processes on single UNIX machines using UNIX named pipes (FIFO pipes). Any process running on a machine which has CCINAMPU installed can access any service on that same machine. CCINAMPU cannot communicate with CCINAMP for OS/2.

Parent topic: CCI Support for UNIX Named Pipes (FIFOs)


Transport Speed

For a given machine CCINAMPU may perform faster than using CCITCP in loopback mode (communicating on a single machine). This is entirely dependant upon the priorities given to each method of communication by the UNIX kernel design on any given system, it is recommended that users try both CCITCP and CCINAMPU and select whichever performs quicker in their own system.

Parent topic: CCI Support for UNIX Named Pipes (FIFOs)


CCI.INI File Options for CCINAMPU

Unlike many other CCI protocol modules, there are no CCI.INI configuration options available when using CCINAMPU.

Parent topic: CCI Support for UNIX Named Pipes (FIFOs)


Application Configuration

CCI Client/Server applications use the CCI Server Name and Machine Name parameters to enable the CCI Client to specify the CCI Server with which to communicate.

The CCI Server identifies itself on the network by using the Server Name parameter. The CCI Client also specifies the CCI Server using the Server Name. Additionally, if it only wants to find this Server running on a particular location within the UNIX machine, it needs to specify the Machine Name parameter.

In other protocols Machine Name is used to specify the individual machine hosting a service, with CCINAMPU Machine Name is used to denote the directory location of the service's listening Named Pipe, as such within a single UNIX system there may be several Services using the same Server Name but residing in different areas of the system.

  • CCINAMPU Server Name
  • CCINAMPU Machine Name
  • Default Service Location
  • Common Error Status
Parent topic: CCINAMPU Configuration


CCINAMPU Server Name

The Server Name specified in the creation of a CCINAMPU server can be one of the following:

  • A relative pipe-name (default)
  • An absolute pipe-name

A relative pipe-name is equivalent to an absolute pipe-name composed of a concatenation of the path /usr/spool/uucppublic/.CCI/ together with a period and the given server name. A relative pipe-name must be at least one character less than the maximum allowed length of a filename for the operating system.

For example, a Server Name consisting of

mainsrvr

would generate a named-pipe with the name /usr/spool/uucppublic/.CCI/.mainsrvr which would be unique on the machine in use.

The only restriction for using an absolute pipe-name is that the pipe name must be of a file layout supported by the host machine's file system.

An example of an absolute pipe-name is:

/u/work/pipespace/mainsrvr

This creates a pipe at the exact location specified. If the user attempting to create the pipe does not have permissions to use the requested directory, CCINAMPU issues an error.

All absolute pipe-names must start with a leading slash (/).

Parent topic: Application Configuration


CCINAMPU Machine Name

The CCINAMPU client initialization function always assumes that a Server Name is a relative pipe-name when it is passed an empty Machine Name parameter. When CCI-Initclient is passed a non-empty Machine Name parameter, the pipe-name searched for is composed of the absolute Server Name with the Machine Name preceding it to form the complete absolute path.

Thus if Server Name is passed as:

mainsrvr

and Machine Name is passed as:

/u/work/pipespace

the resultant pipe that is searched for would be /u/work/pipespace/mainsrvr

and would connect with the example of an absolute servername used in the description for starting a CCINAMPU server given above.

An absolute pipe-name must be consistent with any limitations of the file system in use on the host machine at all times. You should be aware that file permissions apply to named-pipes as well as to files.

Absolute pipe-names cannot be used across network file systems (NFS) successfully. Therefore, we recommend that relative pipe-names are used for simplicity in the majority of applications.

Parent topic: Application Configuration


Default Service Location

Unlike CCITCP, there is no central registration module for CCINAMPU. Any Server Name given to CCINAMPU as a relative pipe name, for example, "SRVS" appears as a pipe-file in the directory /usr/spool/uucppublic/.cci/.SRVS.

These are not normal files but they are affected by access permissions. So, if a server doesn't respond to a client's request, the first check should be made on access permissions. All files, and the directory itself, should have READ and WRITE permissions for all processes.

Parent topic: Application Configuration


Common Error Status

When running an application which uses CCINAMPU, if an error occurs when starting either the client or the server components, and the error status indicates that the system was too busy to create a new pipe, then it is most likely that the access permission set in the service location directory - for default service locations /usr/spool/uucppublic - is incorrect. The permission must be set to 777 for CCINAMPU to function correctly for all users at all times.

Parent topic: Application Configuration


CCI Trace

  • Activating CCI Trace
  • CCI Trace Options
Parent topic: Configuring CCI
Related information
Configuring CCI Introduction
CCITCP Configuration
CCINAMPU Configuration
CCI.INI - The CCI Configuration File
CCI Status Messages


Activating CCI Trace

To activate CCI Trace add the following /tr parameter setting to the Fileshare Server configuration file.

/tr cci

To prevent unauthorized access to the CCI Trace information you are prompted for the supervisor password when you invoke a Fileshare Server with CCI Trace enabled (the supervisor password is that specified for the user-ID FSVIEW in the password file so you must specify this password when you start the Fileshare Server). If the password is accepted CCI Trace is enabled and a second prompt asks if CCI Trace should be activated immediately or not.

CCI Trace can be toggled on and off using the F3 key.

Parent topic: CCI Trace


CCI Trace Options

  • CCITRACE Environment Variable
  • CCI.INI Trace Options
Parent topic: CCI Trace


CCITRACE Environment Variable

CCI trace can be enabled for any application by setting the CCITRACE environment variable as follows:

CCITRACE=filename [options]

where:

filename
The name of the log file you want the trace output to go to. If you do not specify this parameter, the log file ccitrc1.trc is created in the current directory with all options set to their default states. A matching filename.idx will also be generated.
options
Any, or all, of the following:
/F or -F | logs the details of CCI API calls to the trace file. The default condition for this option is OFF, unless a filename or any other trace option are specified, in which case it is always ON.
/P or -P | logs the details of protocol level calls to the trace file. If this flag is not ON, then only the details of the CCI user level API will be traced. If this flag is ON, the level of function tracing may be greatly increased. The default condition for this option is OFF.
/D or -D | logs the contents of all buffers passed to and from the CCI functions. The default condition for this option is OFF. Data tracing may not be allowed if the application has been coded to prohibit data tracing for security reasons.

So to create a CCI trace file with the default name of ccitrc1.trc (with matching ccitrc1.idx file) which traces CCI API function flow, along with the underlying protocol function flow, but with no tracing of the user data passed to these calls, the value of the CCITRACE environment variable would be /P.

The CCI.INI file can also be used to control trace options, but any values specified by the CCITRACE environment variable will take precedence.

Parent topic: CCI Trace Options


CCI.INI Trace Options

CCI trace options can be specified via the CCI.INI file. These options are listed under the [ccitrace-base] section.

Option | Value | Meaning
force_trace_on | yes or no | If yes, logs the details of CCI API calls to the trace file. The default condition for this option is no. Unless this option is specified, no tracing will be generated, even if the other options are specified to yes.
protocol_trace | yes or no | If yes, logs the details of protocol level calls to the trace file. If this option is yes, the level of function tracing may be greatly increased. The default condition for this option is no.
data_trace | yes or no | If yes, logs the contents of all buffers passed to and from the CCI functions. The default condition for this option is no. Data tracing may not be allowed if the application has been coded to prohibit data tracing for security reasons.

For example, to turn on CCI API tracing and data tracing, but not protocol level tracing, the CCI.INI file would need to contain the following

[ccitrace-base]
force_trace_on=yes
protocol_trace=no
data_trace=yes

Note that if trace options have been specified via a CCITRACE environment variable they will take precedence over any trace options specified in the CCI.INI file.

Parent topic: CCI Trace Options


CCI.INI - The CCI Configuration File

  • What is the CCI.INI File?
  • Where to Locate CCI.INI
  • The Format of CCI.INI
  • Specific Contents of CCI.INI for Each CCI Module
Parent topic: Configuring CCI
Related information
Configuring CCI Introduction
CCITCP Configuration
CCINAMPU Configuration
CCI Trace
CCI Status Messages


What is the CCI.INI File?

The CCI.INI file is used to specify selective configuration options for all or some CCI modules installed on a system. The contents of the CCI.INI file will vary from system to system in a network, depending upon the requirements for tuning each individual system.

Parent topic: CCI.INI - The CCI Configuration File


Where to Locate CCI.INI

CCI.INI may be located in a number of locations for testing and deployment. The Windows root directory is a good location as it is visible from all applications, on Windows systems of all types. On UNIX systems, the COBOL cobdir/bin installation directory or the applications current directory are good logical locations. There may be configuration sections for more than one CCI protocol module in any CCI.INI file so care is required when choosing the location for a CCI.INI file. If you only want to affect the behavior of a single application, rather than affecting every application on the system, put the CCI.INI file (containing the CCIIPX entries) in the current directory, from where the application is being run.

Parent topic: CCI.INI - The CCI Configuration File


The Format of CCI.INI

CCI.INI is a plain text file, which may be edited or created by any text editor. A CCI.INI file may look like this:-

[cciipx-base]
  REPORT_CONNTYPES=n
  CRC_SEND=n
  CRC_FORCE_RECV=n
  CRC_REPORT_FAILS=n
  CRC_RETRY=y
  MAX_PKT_SIZE=17872

[ccinetb-base]
  AdapterLoc=0
  DefaultBuffLen=4096
  Commands=20
  Sessions=10
  Names=2

[ccitcp-servers]
  myserver=MFPORT:3000
Parent topic: CCI.INI - The CCI Configuration File


Specific Contents of CCI.INI for Each CCI Module

The following sections describe the usage of CCI.INI file for all the available CCI modules.

  1. There are no CCI.INI tuning options for CCIAPPC
  2. CCI.INI usage for CCIIPX
  3. CCI.INI usage for CCINETB
  4. CCI.INI usage for CCITCP
  5. There are no CCI.INI tuning options for CCINAMPU
  6. CCI.INI usage for CCI Trace
Parent topic: CCI.INI - The CCI Configuration File
Related information
CCI.INI usage for CCITCP
CCI.INI usage for CCI Trace


CCI Status Messages

  • CCI Status Messages
  • CCI Message Table
Parent topic: Configuring CCI
Related information
Configuring CCI Introduction
CCITCP Configuration
CCINAMPU Configuration
CCI Trace
CCI.INI - The CCI Configuration File


CCI Status Messages

All CCI modules produce text based error messages describing the status of the completion of the last CCI operation. Some errors are critical and require remedial action before use of the affected CCI module can continue. Others are warnings and, in most cases, do not require you to take any action.

When an error occurs in the communications layer the CCI status codes returned to calling applications will change to reflect the underlying problem that has occurred. All CCI enabled applications can then make a call to CCI to obtain a text message describing the problem.

The manner in which these messages is returned to the application user is specific to each application, however the actual text returned from CCI is the same in all cases. The sections below indicate what the status messages mean, and what steps can be taken by the user to correct the situation which created the error status in the first place.

The text format used for all CCI messages is as follows:-

"CCINETB-0001I A CCINETB call has timed-out."

This is broken down in to the following sections:

  • Protocol issuing the message - "CCINETB"
  • Message number - "0001"
  • Severity level - "I"
  • Message text.- "A CCINETB call has timed-out."

Not all the available messages are produced by all the protocol modules, there are also messages which are specific to individual aspects of configuration on specific protocol environments. Some status are intended for use only during the development of CCI enabled applications, where these status are seen by the end user they should contact our technical support staff and report the situation and applications which generated the status condition.

Parent topic: CCI Status Messages


CCI Message Table

The following is a list of status numbers returned which may be produced from CCI modules, along with a brief explanation of their meaning, and, if applicable, a suggestion as to how to resolve the issue being reported. Status numbers which are produced to aid coding of CCI applications have been included in this list.

Message Number | Severity | Reason | Suggestion
0000 | Information | The last operation completed successfully | No action to take
0001 | Information | The last operation Timed-out prior to completion. | Increase time-out periods if the application allows, or check the status of the remote application to ensure that its host system is still functioning.
0002 | Information | A buffer given to a CCI receiving operation was too small to contain the incoming data stream. | This is a warning intended for applications designers. Contact us if you suspect that this is actually causing a problem.
0003 | Error | A bad parameter was given to a CCI function. | This is a application coding problem. Contact our technical support department and report any of these errors that appear.
0004 | Warning | This is only generated from a Service initiation. This status indicates that a Service with the same name was previously registered at the same network address. | No action required, the current Service is now registered with the network, connecting clients will connect to this Service.
0005 | Error | This is only generated from a Service initiation. This status indicates that a Service with the same name was previously registered at the same network. | Two services cannot exist on some networks with the same Service name, choose another name to start this Service with.
0006 | Error | A name parameter passed being used to start a client or a Service was invalid. | The range of valid names differs for underlying protocols, please see the sections for the relevant CCI module for the protocol in use for this information.
0007 | Error | An attempt was made to use a connection which has already been terminated. | This is a application coding error, contact our technical support department and report any occurrence of this error.
0008 | Error | A broken connection was detected on this link. | Check the status of the network supporting this link and determine whether the problem lies at the network or at the machine at the far end of the link.
0010 | Warning | The CCI module in use was too busy to complete the request. | Allow some of the outstanding CCI actions to complete before trying again.
0011 | Warning | The CCI module discovered that the system was too low on memory to complete an action. | Close any unwanted applications, and free up some memory to allow the application to continue.
0012 | Error | No service was found, the client could not complete a connection request. | Check the address passed as a location to the client and try again.
0013 | Error | The address specified in the direct addressing modes would not accept a client connection. | Check the address passed as a location to the client and try again. The service listening at the far end may not be compatible with a CCI client.
0014 | Error | An error occurred when creating a network endpoint. | The local network service provider was incapable of creating a new connection point, this usually means that a resource limit has been reached, or that the network itself is disabled. Check the system status and raise network resources as appropriate.
0015 | Error | A transport error has occurred | CCI full network transport failure has been reported to CCI from the transport provider. Check the network status, correct any problems that are found and try again.
0016 | Error | A CCI support module was not found on the network. | Some CCI protocols and configurations require network support modules, such as CCITCP2, please check to ensure that you have configured your network correctly to use CCI, and that the required support modules are running before starting CCI, then try again.
0017 | Error | A transport connection error has occurred | Where possible CCI will distinguish between this message and message 0016. This message indicates that an individual connection has failed, rather than a general network failure occurring. Check the application at the far end of the link to ensure that it is still functioning.
0018 | Information | An asynchronous call has not completed yet. | This status is intended for application programmers to monitor the status of an ongoing operation, it may be ignored by end users.
0019 | Information | An asynchronous call has completed correctly. | This status is intended for application programmers to monitor the status of an ongoing operation, it may be ignored by end users. It is functionally equivalent to status "0000".
0020 | Information | An asynchronous call has completed part one of a two part operation.. | This status is intended for application programmers to monitor the status of an ongoing operation, it may be ignored by end users.
0021 | Error | An error occurred when closing a session. | This could be a network or operating system failure, however a failure at this time may not affect the overall running of an application. Contact our technical support department if you suspect that this is actually causing a problem.
0022 | Error | This is only generated from a Service termination. Could not de-register a service | There was a problem when terminating a service that prevented it being de-registered from the CCI support modules such as CCITCP2, or from the network provider itself. Subsequent attempts to start a Service with the same name will generate messages 0004 or 0005 depending upon the network which is being used.
0023 | Error | This is only generated from a Service application. A client connection could not be completed due to a network level error condition. | The network service provider reported a failure to allow a full connection of an incoming client. Check the connecting clients to determine which of them is failing to connect, then check the network provider on the client and server machines for version compatibility.
0024 | Error | A call to HANGUP a server session could not complete as data was still queued. | This is an application coding error. Contact our technical support department.
0025 | Error | Transport initialization failure, INITCLIENT could not find CCITCP2, | The UDP support in the TCP/IP service provider configuration may be switched off, or may have run out of available resources. Ensure that UDP is enabled and that sufficient sockets are available, then try again.
0026 | Error | Transport initialization failure during INITCLIENT. | Check the version details of the network service provider to ensure that CCI is compatible with this level of network provider.
0027 | Error | A call to CCI-Query was made with an invalid session handle. | This is an application coding error. Contact our technical support department.
0028 | Error | A call to CCI-Wait was made with an invalid session handle. | This is an application coding error. Contact our technical support department.
0029 | Error | Parameters were incorrectly passed to the call named in the text. | This is an application coding error. Contact our technical support department.
0030 | Error | A listen call failed as the machine was too busy to receive any more incoming client connections. | The system configuration is too small to support the connection load being used, either increase the system capacity for the protocol in use, or reduce the load on this specific system by examining other possible alternative to using this system.
0031 | Error | A CCI function detected a transport failure during an attempt to receive a data buffer. | The network, or the machine at the far end of the connection, experienced an error condition, correct the network error and try again.
0032 | Error | CCI-Transact function detected a transport failure during an attempt to send a data buffer. | The network, or the machine at the far end of the connection, experienced an error condition, correct the network error and try again.
0033 | Error | CCI-Transact function detected a transport failure during an attempt to receive a data buffer. | The network, or the machine at the far end of the connection, experienced an error condition, correct the network error and try again.
0034 | Error | CCITCP could not find an entry for "mfcobol" in the "services" TCP/IP configuration file. | An entry such as : 'mfcobol <TAB> 86/udp' must be included in the file for CCI to establish a registration ,or make a registration enquiry with a CCITCP2 module.
0035 | Error | The far end of a connection has been reset. | Check this status of the remote end of a connection as it appears to have dropped off the network.
0036 | Information | CCITCP2 could not be found, a CCI Service could not de-register correctly from CCITCP2. | The Service registration module, CCITCP2, may have been closed or the network link to the machine hosting CCITCP2 may have died. If CCITCP2 is still running any requests for this Service will find a registration which is not responding to Client connection attempts. Any further requests to register the Service by the same name will get a status "0004" returned as it was already registered. See the CCITCP configuration guide for further details about using CCITCP2.
0037 | Error | An invalid service handle was passed to the CCI function named in the text. | This is an application coding error. Contact our technical support department.
0038 | Error | An invalid async' request handle was passed to CCI-Query or CCI-Wait. | This message has been superseded by "0027" and "0028" and should only be found on older CCI installations. See "0027" and "0028" for the correct action to take.
0039 | Warning | A data buffer and length combination given to CCI crossed a segment boundary in memory. Data was truncated at this boundary. | This is an application coding error. Contact our technical support department.
0040 | Error | A call to CCI-Suspend was made prior to a call to CCI-Resume. | This is an application coding error. Contact our technical support department.
0041 | Error | A call to initialize a network service provider has failed | Check the network support for the system and correct any problems found, then try again.
0042 | Error | Could not attach to a Network Server | This CCIIPX message indicates that no NetWare server has been found on your network. CCIIPX cannot operate with a NetWare server on its network and so cannot continue.
0043 | Error | Cannot connect to an incompatible version of CCI | A connection has been requested between dissimilar CCI installations, this has been detected and to prevent possible data flow problems a connection cannot be completed. please check the revisions in use and update the CCI installations as required before trying again.
0044 | Error | Could not register a service | This could be a configuration error, see CCITCP2, or the underlying network could have failed to allow the registration due to insufficient capacity of available resources, see message 0025.
0045 | Error | A bad address was passed to a CCI initialization call. | Check that the addresses used in the configuration are of the correct style and content for the CCI module being used, then try again.
0046 | Error | CCIAPPC failed to locate an APPC session | Ensure that the local LU is defined for this session.
0047 | Error | A call to CCI failed as CCI has already been terminated. | This is an application coding error. Contact our technical support department.
0048 | Error | A bad data buffer location was passed to CCI for use in sending or receiving data. | This is an application coding error. Contact our technical support department.
0049 | Error | CCI-Trace was unable to create trace output files for the CCI module named in the text. | There may be insufficient space left on the fixed disk to hold the data trace file. Please clear some space and try again.
0050 | Error | The requested CCI-TRACE output file could not be opened | Check that write permissions are available for the user of the application being traced, and that there is sufficient disk space remaining to store the trace file before trying again.
0051 | Error | An unexpected CCI error has occurred. | This is an internal CCI error. Contact our technical support department.
0052 | Information | This status is reserved for future use. |
0053 | Information | This status is reserved for future use. |
0054 | Information | This status is reserved for future use. |
0055 | Warning | Cannot send or receive data on a suspended session. | This is an application coding error. Contact our technical support department.
Parent topic: CCI Status Messages
Related information
CCITCP2


File Handling Reference

  • Configuration File
    Certain aspects of the File Handler's behavior can be configured. You can alter these aspects by entering values in the File Handler configuration file.
  • Operation Codes
    View the standard and special operation codes for all file organizations.
  • File Status
    View the full definitions of the two-digit file status codes.
  • MFSORT and MFJSORT Utilities
    Visual COBOL provides MFSORT, a command line sort and merge utility, and MFJSORT, an emulator for DFSORT and SYNCSORT.
  • Sorting Files
    Use the environment variables to affect the running of a sort operation, and use the FCD codes and error messages to help troubleshoot failed sort operations.
  • Tracing File Operations
    Use the tracing file operations, which are provided to help in investigations into problems with file handling.
Parent topic: Micro Focus COBOL Server for UNIX


Configuration File

The default filename for the File Handler configuration file is extfh.cfg but you can use a different filename by setting the EXTFH environment variable. For example:

set EXTFH=/mydir/test.cfg
sets the filename to /mydir/test.cfg.
  • Format of the Configuration File
    The File Handler configuration file enables you to apply settings to individual or groups of files by adding options to different sections in the file.
  • Configuration File Options
    The File Handler configuration file can contain a number of options that affect file handling operations in this COBOL system.
Parent topic: File Handling Reference


Format of the Configuration File

The File Handler configuration file enables you to apply settings to individual or groups of files by adding options to different sections in the file.

When a file handling action is performed, applicable settings are applied in the order that the sections are listed below:

  • XFH-DEFAULT
  • FOLDER tag
  • Extension tag
  • INTERNAL tag
  • Filename tag
  • Path and filename tag
  • Example
Parent topic: Configuration File


XFH-DEFAULT

Settings that apply to all files are listed under the tag:

[XFH-DEFAULT]

Two further tags are available to use within [XFH-DEFAULT] or instead of it. Settings that apply to all indexed files or all sequential files are listed under these tags:

[IDX-DEFAULT] and [SEQ-DEFAULT]
Parent topic: Format of the Configuration File


FOLDER tag

Settings that apply to all files in a specific folder are listed under the FOLDER tag, for example:

[FOLDER:usr/files/acufiles]
FILESUFFIX=dat

[FOLDER:C:/files/rmfiles]
IDXFORMAT=21

sets all files in usr/files/acufiles that do not have a suffix to .dat, and all indexed files in usr/files/rmfiles to an IDXFORMAT of 21.

Note: When searching along a path, if a FOLDER tag exists for a stage, settings at that stage are applied, with any conflicting settings overwritten by a subsequent stage. Using the example above, if there was also a FOLDER tag for usr/files that sets IDXFORMAT 2, the subsequent setting of IDXFORMAT 21 would overwrite this.
Parent topic: Format of the Configuration File


Extension tag

Settings that apply to files of the same file extension are listed under the specific extension tag, for example:

[*.DAT]
IDXFORMAT=2

sets all files with a .DAT extension to an IDXFORMAT of 2.

Parent topic: Format of the Configuration File


INTERNAL tag

The settings for an individual file override the global settings. If you just specify the filename, it must be the resolved filename, that is, the filename that the File Handler uses after it has completed its filename mapping process. Alternatively, you can prefix the filename with the keyword INTERNAL, to signify that the filename is the name that is used in the SELECT clause; the settings will then be applied to the file that is identified at the conclusion of the filename mapping process. For example, if the ASSIGN mode is dynamic, and you code:

.
[INTERNAL:$myfile/outfile.dat]
IDXFORMAT=8

where myfile is an environment variable holding the name of the directory where the folder is located, the settings will be applied to outfile.dat in that directory.

If the ASSIGN mode is external, and you had:

SELECT MYDATA ASSIGN TO EXTERNAL REALDATA

you could code:

[INTERNAL:REALDATA]

where any options which follow apply to the file to which the logical name "REALDATA" is mapped.

If, however, you have:

.
SELECT MYDATA ASSIGN TO '/directory/subdirectory/datadirectory/myfile'

you cannot use the INTERNAL option in the configuration file. The literal value in the SELECT statement must be replicated [inside square brackets] in the configuration file.

Filenames can use paths and DD_mappings but not wildcards or logic names. If you set the File Handler configuration option BASENAME=ON, you can specify filenames without paths. Note that the name of a file must match the mapped name in your program.

Parent topic: Format of the Configuration File


Filename tag

Settings that apply to a specific file are listed under the specific filename tag; for example:

[file1.dat]
IDXFORMAT=17
[file2.dat]
IDXFORMAT=21

sets file1.dat to IDXFORMAT 17 and file2.dat to IDXFORMAT 21.

Comments:

To enable the use of filenames (without a pathname), set BASENAME=ON in the [XFH-DEFAULT] section.

When you use the filename tag, the path to the current directory is assumed, and if a FOLDER tag exists for any folder along the path, settings for that tag are applied. For example, if you have the following file assignment:

SELECT myFile ASSIGN TO 'file1.dat'

and your application is run in the directory usr/files/mffiles, then if you have FOLDER tags for the following locations in your configuration file, the settings in them are applied:

  • usr
  • usr/files
  • usr/files/mffiles
Parent topic: Format of the Configuration File
Related reference
Path and filename tag
BASENAME


Path and filename tag

You can explicitly specifiy a file using the path and filename tag; for example:

[usr/acufiles/file1.dat]
IDXFORMAT=17
[usr/rmfiles/file1.dat]
IDXFORMAT=21

sets file1.dat in usr/files/acufiles to IDXFORMAT 17 and file1.dat in usr/files/rmfiles to IDXFORMAT 21.

Note: To enable the use of filenames (without a pathname), set BASENAME=ON in the [XFH-DEFAULT] section.
Parent topic: Format of the Configuration File
Related reference
Filename tag
BASENAME


Example

According to the order that the options are applied, the following excerpt of the File Handler configuration file:
[XFH-DEFAULT]
IDXFORMAT=2
[*.dat]
IDXFORMAT=8
[FOLDER:C:\\files\\acu]
IDXFORMAT=17
results in myfile.dat, located in c:\files\acu, being set to IDXFORMAT 17.
Parent topic: Format of the Configuration File


Configuration File Options

The following options can be set in the File Handler configuration file.

  • ASCIIMAINFRAMEPRINT
    The ASCIIMAINFRAMEPRINT option specifies whether to use ASCII printer control characters when CHARSET is set to ASCII and the FILETYPE is set to mainframe print format where “WRITE BEFORE ADVANCING SYNTAX” is used.
  • BASENAME
    The BASENAME option determines whether filenames specified in tags can be expressed without pathnames. By default, such filenames have to be expressed with full path information as passed to the File Handler by the calling program. By setting BASENAME=ON, it is possible to specify the filename without the path.
  • C$FORMAT
    The C$FORMAT option determines the default file format for actions performed using the C$COPY, C$DELETE, and RENAME file handling library routines.
  • COMMITFLUSH
    In the context of a program that is not using Fileshare, the COMMITFLUSH option specifies whether the COMMIT and ROLLBACK statements cause all file updates to be flushed to disk, as well as record locks to be released.
  • CONCATNAME
    The CONCATNAME option determines whether filenames including the plus ('+') character are to be interpreted as normal filenames, or as file concatenations.
  • CONVERTDBSPACE
    The CONVERTDBSPACE option enables conversion of double-byte character set (DBCS) spaces to ASCII spaces when reading a line sequential file.
  • CONVERTEUCKATAKANA
    The CONVERTEUCKATAKANA option enables conversion of EUC single-width double-byte characters to their double-width Katakana equivalents when reading a line sequential file.
  • CONVERTSTATUS
    The CONVERTSTATUS option specifies the name of a program that is called after the File Handler has finished processing to map returned status values for emulation purposes.
  • DATACOMPRESS
    The DATACOMPRESS option specifies whether data compression is in effect and the type of compression. The directive only affects record sequential and indexed files.
  • DATAFILE
    The DATAFILE option maps the filename passed to an OPEN statement onto another name.
  • EXPANDPOSITIONING
    When using the WRITE AFTER POSITIONING statement (OS/VS COBOL compatibility), the first character of the record area can hold carriage control information. The EXPANDPOSITIONING option determines whether the written record includes this carriage control information.
  • EXPANDTAB
    The EXPANDTAB option determines whether to expand TAB characters encountered in line sequential or line advancing files during a READ operation into the equivalent number of spaces.
  • FASTREAD
    The FASTREAD option specifies whether or not the File Handler performs extra checking to ensure data integrity when reading an indexed file.
  • FHREDIR
    The FHREDIR option specifies whether a remote server using Fileshare can handle files.
  • FILECASE
    The FILECASE option enables you to adjust the case of data file names.
  • FILESUFFIX
    The FILESUFFIX option specifies the file extension to be used for files that do not explicitly specify one. This option is switched on/off according to file organization, by using the IDXNAMETYPE, SEQNAMETYPE, LSEQNAMETYPE, and RELNAMETYPE configuration options.
  • FILEMAXSIZE
    The FILEMAXSIZE option specifies the number of bytes used internally to store file offsets.
  • FILEPOINTERSIZE
    For format 8 indexed files, the FILEPOINTERSIZE parameter specifies the length in bytes to use to store file pointers.
  • FSIDXINTEGRITY
    In the context of a Fileshare system, the FSIDXINTEGRITY option causes any changed nodes held within the File Handlers index cache (as configured with the INDEXCOUNT option) to be written to disk before Fileshare returns status information to the client program. This option improves the integrity of indexed files processed by Fileshare at the expense of a small amount of additional file I/O.
  • IDXDATBUF
    The IDXDATBUF option determines the size of buffer used when accessing the data portion of a file with organization INDEXED.
  • IDXFORMAT
    The IDXFORMAT option specifies the format to use when creating indexed files.
  • IDXNAMETYPE
    The IDXNAMETYPE option specifies the format of the filename type for both the data file and, if present, the index file.
  • IGNORELOCK
    The IGNORELOCK option specifies whether to ignore locks when reading files open for input.
  • INDEXCOUNT
    The INDEXCOUNT option specifies the number of index nodes to be cached for an indexed file.
  • INDEXFILE
    The INDEXFILE option maps the name of the index file (for those indexed file formats that have a separate index file). This name can include full path information.
  • INSERTNULL
    When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTNULL option determines whether to insert NULL (x"00") characters before non-printable characters. The option also determines whether to strip out those NULL characters during READ operations.
  • INSERTTAB
    When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTTAB option determines whether to replace sequences of spaces with TAB characters.
  • INTEROP
    The INTEROP option determines which file handler is used for all file organizations in a given folder.
  • KEYCHECK
    The KEYCHECK option specifies whether the File Handler checks that the key definition defined in your application matches that of the indexed file you are opening.
  • KEYCOMPRESS
    The KEYCOMPRESS option specifies the type of key compression in use.
  • LOADONTOHEAP
    The LOADONTOHEAP option specifies whether the File Handler loads the file into memory before executing any I/O operations.
  • LOCKTYPE
    The LOCKTYPE option specifies the type of record locking in use.
  • LOG
    When LOG is set to ON, any unusual file-related situations, such as corrupted files, or automatic file recovery, are noted in a log file for later examination.
  • LOGFILENAME
    When the LOG option is active, the LOGFILENAME option specifies the name of the log file to produce.
  • LSEQNAMETYPE
    The LSEQNAMETYPE option determines if the FILESUFFIX option is used for line sequential files that do not explicitly specify a file extension.
  • LSFILETERM
    The option controls the behavior of the File Handler upon encountering the EOF character x"1a" when reading line sequential files.
  • LSRECDELIM
    The LSRECDELIM option specifies the characters to be used as the record delimiter in line sequential files.
  • MAINFRAMEPRINT
    For those files using WRITE AFTER ADVANCING or WRITE BEFORE ADVANCING, the MAINFRAMEPRINT option determines whether to use mainframe printer file format (filetype 11).
  • NAMEOPTIONS
    The NAMEOPTIONS option specifies whether the name you pass to the OPEN statement can contain File Handler options.
  • NFSFILELOCK
    The NFSFILELOCK option enables applications to detect record locks and file locks on UNIX NFS file systems.
  • NODESIZE
    The NODESIZE option specifies the size of the index nodes to use for an indexed file.
  • NOSEQCHECK
    The NOSEQCHECK option disables sequence-checking of keys in indexed files.
  • OPENINPUTSHARED
    The OPENINPUTSHARED option specifies whether files that you open for input, and for which you do not specify a LOCK MODE clause, can be shared by other users.
  • OSVSREWRITE
    The OSVSREWRITE option specifies whether to permit the WRITE statement for sequential files that are open for output. If so, these WRITE statements behave exactly like REWRITE statements.
  • READSEMA
    The READSEMA option specifies whether the system attempts to gain a semaphore for shared files when I/O operations are performed that do not modify the file.
  • READTODELIM
    The READTODELIM option specifies whether the file pointer is advanced to the next logical record in the file when reading in a record that is longer than the user data area. In these circumstances, the data record would effectively be truncated.
  • RELDATBUF
    The RELDATBUF option determines the size of buffer used when accessing a file with organization RELATIVE.
  • RELNAMETYPE
    The RELNAMETYPE option determines if the FILESUFFIX option is used for relative files that do not explicitly specify a file extension.
  • RELRECDELIM
    The RELRECDELIM option specifies the characters to be used as the record delimiter in fixed-length relative files.
  • RETRYLOCK
    The RETRYLOCK option indicates whether you wish to retry a READ operation that fails because the record is locked.
  • RETRYOPEN
    The RETRYOPEN option indicates whether you wish to retry an I/O operation that fails because the file is locked.
  • RETRYTIME
    The RETRYTIME option specifies whether the integer given in the RETRYLOCK and RETRYOPEN options specifies the number of attempts or the number of seconds.
  • RUNITLOCKDETECT
    The RUNITLOCKDETECT option specifies whether the File Handler checks whether a record has been locked by a separate OPEN statement issued from within the same run unit.
  • SEARCHONCREATE
    The SEARCHONCREATE parameter determines whether the File Handler searches each specified directory on a multi-directory path for a file with the same name as the one being created. This option applies only to files which are opened with OPEN OUTPUT.
  • SEQDATBUF
    The SEQDATBUF option determines the size of buffer to use when accessing a file with organization SEQUENTIAL.
  • SEQNAMETYPE
    The SEQNAMETYPE option determines if the FILESUFFIX option is used for sequential files that do not explicitly specify a file extension.
  • SKIPLOCK
    The SKIPLOCK option specifies whether to advance the current record pointer when a locked record is encountered during a sequential READ.
  • SPACEFILL
    The SPACEFILL option determines whether to fill with spaces that part of the record area beyond the data that is read when performing READ operations on line sequential or line advancing files.
  • STARTUNLOCK
    The STARTUNLOCK option determines whether a START operation will remove existing locks for files specified with single record locking; that is, without the WITH LOCK ON MULTIPLE RECORDS phrase.
  • STRIPSPACE
    The STRIPSPACE parameter determines whether to remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.
  • SUPPRESSADV
    The SUPPRESSADV option determines whether to ignore the ADVANCING phrase of the WRITE statement for record sequential files.
  • TRACE
    The TRACE option specifies whether Xfhtrace, the File Handler trace module, is enabled. The Xfhtrace module traces File Handler operations and logs all activity to a trace file. It is supplied to help you diagnose any problems you may have with COBOL files.
  • TRACEFILEEXTEND
    The TRACEFILEEXTEND option determines whether to write trace information to the end of the current trace file, if the trace file already exists. This option has no effect if TRACE is OFF.
  • TRACEFILENAME
    The TRACEFILENAME option specifies the name of the trace file to produce when the TRACE option is active.
  • USEVSAMKEYDEFS
    Use the keys defined in the catalog via the JCL and IDCAMS instead of the keys defined in the executing program.
  • WRITELINE
    The WRITELINE parameter determines whether mainframe or PC behavior is used for WRITE record.
  • WRITETHRU
    The WRITETHRU option determines whether modifications to a file are written out to disk immediately or buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.
Parent topic: Configuration File


ASCIIMAINFRAMEPRINT

The ASCIIMAINFRAMEPRINT option specifies whether to use ASCII printer control characters when CHARSET is set to ASCII and the FILETYPE is set to mainframe print format where “WRITE BEFORE ADVANCING SYNTAX” is used.

Syntax:

ASCIIMAINFRAMEPRINT = { ON } { OFF }

Parameters:

ON
Printer Control Characters are in ASCII when CHARSET is set to ASCII.
OFF
Printer Control Characters are in EBCDIC where CHARSET is set to ASCII.

Properties:

Default: OFF

Comments:

You use an entry in the File Handler Configuration File (EXTFH.cfg) to enable the printer control characters to be ASCII when the CHARSET is set to ASCII:

[xfh-default]
 ASCIIMAINFRAMEPRINT=ON

The default value is OFF.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


BASENAME

The BASENAME option determines whether filenames specified in tags can be expressed without pathnames. By default, such filenames have to be expressed with full path information as passed to the File Handler by the calling program. By setting BASENAME=ON, it is possible to specify the filename without the path.

Syntax:

BASENAME = { ON } { OFF }

Parameters:

ON
Filename tags can be expressed without path information.
OFF
All filename tags in the configuration file must be expressed with full path information.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options
Related reference
Filename tag
Path and filename tag


C$FORMAT

The C$FORMAT option determines the default file format for actions performed using the C$COPY, C$DELETE, and RENAME file handling library routines.

Syntax:

C$FORMAT = format

Parameters:

format
The file format used for operations performed by the library routines C$COPY, C$DELETE, and RENAME. Must be one of:
0
Default format for the operating system (identical to 8.)
1
C-ISAM.
3
Micro Focus default indexed file format.
4
Optimized format for fast duplicate key handling.
5
Reserved.
6
Reserved.
8
Large indexed file format.
9
Indexed with single key, non-duplicate, key ordered records.
10
Reserved.
11
Mainframe print file format.
12-13
Reserved.
14
Heap file.
15
ESDS
16
ESDS-Big
17
Vision
18
MySQL
19
Oracle
20
DB2
21
RM
22-255
Reserved.

Properties:

Default: 17

Comments:

You can specifiy this option in [XFH-DEFAULT] or any other section of the configuration file.

When you call one of the file handling routines, IDXFORMAT defaults to the value of C$FORMAT, but can then be overriden if specified in the file handling configuration file.

Parent topic: Configuration File Options


COMMITFLUSH

In the context of a program that is not using Fileshare, the COMMITFLUSH option specifies whether the COMMIT and ROLLBACK statements cause all file updates to be flushed to disk, as well as record locks to be released.

Syntax:

COMMITFLUSH = { ON } { OFF }

Parameters:

ON
The COMMIT and ROLLBACK statements cause all file updates to be flushed to disk.
OFF
The COMMIT and ROLLBACK statements do not cause all file updates to be flushed to disk.

Properties:

Default: OFF

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


CONCATNAME

The CONCATNAME option determines whether filenames including the plus ('+') character are to be interpreted as normal filenames, or as file concatenations.

A concatenated file should be opened only for input and should have organization SEQUENTIAL or LINE SEQUENTIAL. It is made up of separate components whose names are separated by the '+' character. On reading sequentially through such a file, when the end of one component is reached and another component is available, the next read will automatically return the first record of that component. On reaching the end of the last component, the AT END status is returned.

Syntax:

CONCATNAME = { ON } { OFF }

Parameters:

ON
Names including the '+' character are treated as concatenated files; for example, the name file1+file2 is treated as the concatenation of files file1 and file2.
OFF
Names including the '+' character are created as normal filenames.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


CONVERTDBSPACE

The CONVERTDBSPACE option enables conversion of double-byte character set (DBCS) spaces to ASCII spaces when reading a line sequential file.

Syntax:

CONVERTDBSPACE = { ON } { OFF }

Parameters:

ON
Convert DBCS spaces to ASCII when reading a line sequential file.
OFF
Do not convert DBCS spaces.

Properties:

Default: OFF
Parent topic: Configuration File Options


CONVERTEUCKATAKANA

The CONVERTEUCKATAKANA option enables conversion of EUC single-width double-byte characters to their double-width Katakana equivalents when reading a line sequential file.

Syntax:

CONVERTEUCKATAKANA = { ON } { OFF }

Parameters:

ON
Convert EUC single-width double-byte characters to their double-width Katakana equivalents.
OFF
Do not convert EUC characters.

Properties:

Default: OFF
Parent topic: Configuration File Options


CONVERTSTATUS

The CONVERTSTATUS option specifies the name of a program that is called after the File Handler has finished processing to map returned status values for emulation purposes.

Syntax:

CONVERTSTATUS = program

Parameters:

program
The name of the program to be called. Three such programs are built into the product:
hoststat
The hoststat program emulates status values returned by IBM Mainframe COBOL compilers.
msstat
The msstat program emulates status values returned by Microsoft COBOL V2.

Properties:

Default: none

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


DATACOMPRESS

The DATACOMPRESS option specifies whether data compression is in effect and the type of compression. The directive only affects record sequential and indexed files.

When set to 0, no data compression takes place. Otherwise, the number indicates the type of compression.

Syntax:

DATACOMPRESS = integer

Parameters:

integer
0
No data compression is performed.
1
Run-length encoding.
3
Run-length encoding for double-byte (DBCS) characters

Properties:

Default: 0
Parent topic: Configuration File Options


DATAFILE

The DATAFILE option maps the filename passed to an OPEN statement onto another name.

Syntax:

DATAFILE = name

Parameters:

name
Name to be mapped to filename; can include full path information.

Properties:

Default: none
Parent topic: Configuration File Options


EXPANDPOSITIONING

When using the WRITE AFTER POSITIONING statement (OS/VS COBOL compatibility), the first character of the record area can hold carriage control information. The EXPANDPOSITIONING option determines whether the written record includes this carriage control information.

Syntax:

EXPANDPOSITIONING = { ON } { OFF }

Parameters:

ON
Use the first character to determine carriage control before stripping the character from the output.
OFF
Write out the whole record, including the carriage control information.

Properties:

Default: OFF
Parent topic: Configuration File Options


EXPANDTAB

The EXPANDTAB option determines whether to expand TAB characters encountered in line sequential or line advancing files during a READ operation into the equivalent number of spaces.

Syntax:

EXPANDTAB = { ON } { OFF }

Parameters:

ON
Expand TAB characters into the equivalent number of spaces.
OFF
Leave TAB characters unchanged.

Properties:

Default: ON
Parent topic: Configuration File Options


FASTREAD

The FASTREAD option specifies whether or not the File Handler performs extra checking to ensure data integrity when reading an indexed file.

Syntax:

FASTREAD = { ON } { OFF }

Parameters:

ON
Do not perform extra checking.
OFF
Perform extra checking to ensure data integrity.

Properties:

Default: ON

Comments:

To increase the efficiency of reads on fixed length, non-compressed indexed files, set FASTREAD to ON.

Parent topic: Configuration File Options


FHREDIR

The FHREDIR option specifies whether a remote server using Fileshare can handle files.

Syntax:

FHREDIR = { ON } { OFF }

Parameters:

ON
Use Fileshare to access files on a remote server.
OFF
Do not use Fileshare.

Properties:

Default: OFF

Comments:

If FHREDIR is set to OFF, the File Handler examines the name at open time to determine whether the file is to be handled locally.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Take care with this option. If it is in effect when Fileshare is running, Fileshare will attempt to redirect file I/O requests to itself, and this will cause a timeout failure.

Parent topic: Configuration File Options


FILECASE

The FILECASE option enables you to adjust the case of data file names.

Syntax:

FILECASE = { 0 } { 1 } { 2 } { 3 } { 4 }

Parameters:

0
Data file names are not changed
1
Data file names are changed to lower case, including directory (path) elements
2
Data file names are changed to upper case, including directory (path) elements
3
Data file names are changed to lower case, excluding directory (path) elements
4
Data file names are changed to upper case, excluding directory (path) elements

Properties:

Default: 0

Examples:

FILECASE=2  *> e.g. cust_acc\fy11.dat becomes CUST_ACC\FY11.DAT
FILECASE=3  *> e.g. CUST_ACC\FY11.dat becomes CUST_ACC\fy11.dat

Comments:

Translation occurs before the filename is mapped with the values in COBDATA or before the FILESUFFIX option is applied. You should make sure that those variables specify the correct case.

Parent topic: Configuration File Options


FILESUFFIX

The FILESUFFIX option specifies the file extension to be used for files that do not explicitly specify one. This option is switched on/off according to file organization, by using the IDXNAMETYPE, SEQNAMETYPE, LSEQNAMETYPE, and RELNAMETYPE configuration options.

Syntax:

FILESUFFIX = suffix

Parameters:

suffix
The file extension to append to a filename that does not explicitly specify one.

Properties:

Default: Not set
Parent topic: Configuration File Options
Related reference
SEQNAMETYPE
LSEQNAMETYPE
IDXNAMETYPE
RELNAMETYPE


FILEMAXSIZE

The FILEMAXSIZE option specifies the number of bytes used internally to store file offsets.

This also affects locking mechanisms: programs sharing the same file all need to use the same FILEMAXSIZE settings to ensure semaphores and record locks are handled correctly, thereby avoiding potential file corruption in shared files.

Syntax:

FILEMAXSIZE = { 4 } { 8 }

Parameters:

4
Limits file addressibility to 32-bit values, which is compatible with earlier versions of Micro Focus products.
8
Allows up to 64-bit values for file addressing on Windows platforms when accessing the NTFS file system, but changes the underlying record locking mechanism. Therefore, if you are sharing very large files (greater than 1Gb in size) all programs accessing the file must use FILEMAXSIZE set to 8 to avoid possible corruption problems.

Properties:

Default: 8

Comments:

Note: Do not set FILEMAXSIZE to 8 under any of the following circumstances:
  • You are running applications on an operating system which does not support a 64-bit file system.
  • You are running applications that access FAT file systems, since such file systems do not support file addressibility greater than 32-bit file addressing.
  • If any accessing program needs to access a shared file in a 32-bit file system.
  • You are sharing files with applications using earlier versions of the Micro Focus COBOL product that only supported 32-bit file access.

Set FILEMAXSIZE to 4 in these scenarios.

All applications accessing a file must run with the File Handler configured with the same value for FILEMAXSIZE.

If you are requesting 64-bit file access to an unknown remote file system, ensure you set the remote_64bit_access tunable.

Only 32-bit (4GB) support is provided for Novell systems.

Parent topic: Configuration File Options


FILEPOINTERSIZE

For format 8 indexed files, the FILEPOINTERSIZE parameter specifies the length in bytes to use to store file pointers.

Syntax:

FILEPOINTERSIZE = { 6 } { 8 }

Parameters:

6
Use 6 bytes, allowing for files up to 256 terabytes.
8
Use 8 bytes, allowing for files over 256 terabytes.

Properties:

Default: 6

Comments:

The FILEPOINTERSIZE=8 option uses up more space to store file pointers. Therefore, the resulting file size might increase slightly.

Parent topic: Configuration File Options


FSIDXINTEGRITY

In the context of a Fileshare system, the FSIDXINTEGRITY option causes any changed nodes held within the File Handlers index cache (as configured with the INDEXCOUNT option) to be written to disk before Fileshare returns status information to the client program. This option improves the integrity of indexed files processed by Fileshare at the expense of a small amount of additional file I/O.

Syntax:

FSIDXINTEGRITY = { ON } { OFF }

Parameters:

ON
Changes to the File Handler's index cache are written to disk before Fileshare returns control the client program.
OFF
Changes to the File Handler's index cache are written to disk when space is needed for other operations.

Properties:

Default: ON

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


IDXDATBUF

The IDXDATBUF option determines the size of buffer used when accessing the data portion of a file with organization INDEXED.

Syntax:

IXDATBUF = { integer } { 0 }

Parameters:

integer
Round up the value that you enter to the next power of 2 that is greater or equal.
0
Do not use buffering.

Properties:

Default: 0

Comments:

A non-zero value can be beneficial while the file is being created. Otherwise, you might not achieve a gain in performance; in fact, performance can be degraded.

For those files where index and data are held in the same physical file, this option has no effect.

Parent topic: Configuration File Options


IDXFORMAT

The IDXFORMAT option specifies the format to use when creating indexed files.

Syntax:

IDXFORMAT = integer

Parameters:

0
Default format for the operating system (identical to 8.)
1
C-ISAM.
3
Micro Focus default indexed file format.
4
Optimized format for fast duplicate key handling.
5
Reserved.
6
Reserved.
8
Large indexed file format.
9
Indexed with single key, non-duplicate, key ordered records.
10
Reserved.
11
Mainframe print file format.
12-13
Reserved.
14
Heap file.
15
ESDS
16
ESDS-Big
17
Vision
18
MySQL
19
Oracle
20
DB2
21
RM
22-255
Reserved.

Properties:

Default: 0

Comments:

You can set IDXFORMATs 17-21 under all tags in the configuration file except the [XFH-DEFAULT] tag.

In cases where the INTEROP and IDXFORMAT settings conflict, the INTEROP setting will override IDXFORMAT.

If you are using Fileshare, IDXFORMATs 17 and 21 do not provide transaction processing capabilities.

Rebuild will not take the setting of this configuration option into account when generating a new file. Refer to the Rebuild Options /t topic in the Reference section for further information.

You can also set the index format using the IDXFORMAT Compiler directive, which will override the setting specified in the file handler configuration file.

Parent topic: Configuration File Options


IDXNAMETYPE

The IDXNAMETYPE option specifies the format of the filename type for both the data file and, if present, the index file.

Syntax:

IDXNAMETYPE = { 0 } { 1 } { 2 } { 3 }

Parameters:

0
Leave the filename of the data file the same. For the index file, discard any extension and add the extension .idx.
1
Leave the filename of the data file the same. For the index file, add the extension .idx.
2
For the data file, add the extension .dat. For the index file, add the extension .idx.
3
For the data file, use the extension in the FILESUFFIX variable if there is no extension. For the index file, add the extension .idx.

Properties:

Default: 1

Comments:

IDXNAMETYPE only affects the data file for Vision files.

The name of the index file (if present) is derived from that of the data file. For example, if the data file name presented to the File Handler is abc.def, the options shown above give the following data and index filenames:

0 | abc.def and abc.idx
1 | abc.def and abc.def.idx
2 | abc.def.dat and abc.def.idx

If the data file name is abc and FILESUFFIX=dat, the following data and index filenames are given for IDXNAMETYPE=3:

3 abc.dat and abc.idx
Parent topic: Configuration File Options
Related reference
INTEROP
FILESUFFIX


IGNORELOCK

The IGNORELOCK option specifies whether to ignore locks when reading files open for input.

Syntax:

IGNORELOCK = { ON } { OFF }

Parameters:

ON
Ignore locks when reading files open for input.
OFF
Do not ignore locks when reading files open for input.

Properties:

Default: OFF
Parent topic: Configuration File Options


INDEXCOUNT

The INDEXCOUNT option specifies the number of index nodes to be cached for an indexed file.

Syntax:

INDEXCOUNT = node-count

Parameters:

node-count
The number of nodes to be cached. Can be any value between 4 and 255.

Properties:

Default: 16
Parent topic: Configuration File Options


INDEXFILE

The INDEXFILE option maps the name of the index file (for those indexed file formats that have a separate index file). This name can include full path information.

Syntax:

INDEXFILE = name

Parameters:

name
The name of the index file.

Properties:

Default: The name of the index file is derived from the name of the data file by adding the extension .idx (see also IDXNAMETYPE).
Parent topic: Configuration File Options
Related information
IDXNAMETYPE


INSERTNULL

When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTNULL option determines whether to insert NULL (x"00") characters before non-printable characters. The option also determines whether to strip out those NULL characters during READ operations.

Syntax:

INSERTNULL = { ON } { OFF }

Parameters:

ON
Insert NULL characters before non-printable characters. Strip out NULL characters during READ operations.
OFF
Do not insert NULL characters before non-printable characters. Do not strip out NULL characters during READ operations.

Properties

Default: ON

Comments:

INSERTNULL takes precedence over the N run-time switch.

If you do not set INSERTNULL, the setting of the N run-time switch determines whether or not NULL characters are inserted before non-printable characters.

Parent topic: Configuration File Options


INSERTTAB

When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTTAB option determines whether to replace sequences of spaces with TAB characters.

Syntax:

INSERTTAB = { ON } { OFF }

Parameters:

ON
Replace sequences of spaces with TAB characters.
OFF
Do not replace sequences of spaces with TAB characters.

Properties:

Default: OFF

Comments:

The setting of the T switch can affect the default setting.

Parent topic: Configuration File Options
Related information
EXPANDTAB


INTEROP

The INTEROP option determines which file handler is used for all file organizations in a given folder.

Syntax:

INTEROP = {ACU} {RM}

Parameters:

Note: These options are case sensitive.
ACU
All Vision file organizations use Vision, the ACUCOBOL-GT file handler.
RM
All file organizations use RMFM, the RM/COBOL file handler.

Example:

In the following excerpt of the configuration file, all file organizations in the folder usr/files/acufiles use the Vision file handler, and all file organizations in the folder usr/files/rmfiles use the RMFM file handler:

[XFH-DEFAULT]
[FOLDER:usr/files/acufiles]
INTEROP=ACU

[FOLDER:usr/files/rmfiles]
INTEROP=RM

Comments:

If you are only handling indexed files, you can also use the IDXFORMAT settings of 17 for Vision files and 21 for RM files.

In cases where the INTEROP and IDXFORMAT settings conflict, the INTEROP setting will override IDXFORMAT.

INTEROP does not affect database file organizations.

The values for this option must be entered in upper case; invalid values are ignored.

Parent topic: Configuration File Options
Related reference
IDXNAMETYPE


KEYCHECK

The KEYCHECK option specifies whether the File Handler checks that the key definition defined in your application matches that of the indexed file you are opening.

Syntax:

KEYCHECK = { ON } { OFF }

Parameters:

ON
All key definitions must match; otherwise a 3/9 error is returned.
OFF
Open the file, regardless of whether key definitions match or not. Any explicit reference, in the program, to a key which does not match an actual key in the file,results in an error at the time of reference.

Properties:

Default: ON
Parent topic: Configuration File Options


KEYCOMPRESS

The KEYCOMPRESS option specifies the type of key compression in use.

Syntax:

KEYCOMPRESS = integer

Parameters:

0
Key compression is not in use.
1
Duplicater key compression is in use.
2
Leading character compression is in use.
4
Trailing space compression is in use.
8
Trailing null compression is in use.

Properties:

Default: 0

Comments:

To specify a combination of the various types of compression, add together the appropriate numbers. For example, 3 specifies duplicate key compression and leading character compression.

Note:
  • Trailing space compression and trailing null compression are mutually exclusive.
  • The KEYCOMPRESS parameter affects key compression for all indexes belonging to the file.
Parent topic: Configuration File Options


LOADONTOHEAP

The LOADONTOHEAP option specifies whether the File Handler loads the file into memory before executing any I/O operations.

Syntax:

LOADONTOHEAP = { ON } { OFF }

Parameters:

ON
The File Handler loads the entire file into memory when it opens the file, executes I/O operations on the file in memory, and writes the file back to disk when it is closed.
OFF
The File Handler leaves the file on disk and executes I/O operations on the file on disk.

Properties:

Default: 0FF

Comments:

  • You can set LOADONTOHEAP to ON only for non-shared files.
  • You should use the ON setting with care and only on small files.
Parent topic: Configuration File Options


LOCKTYPE

The LOCKTYPE option specifies the type of record locking in use.

Syntax:

LOCKTYPE = integer

Parameters:

0
Programs can read locked records, but cannot access them in other ways. This is the standard method with this COBOL system.
1
Programs cannot access locked records at all. This is as in languages other than COBOL.
2
Creates a new file with the same base name as the file being opened but with a .lck extension. Any record locks are recorded in this file.

Properties:

Default: 0
Parent topic: Configuration File Options


LOG

When LOG is set to ON, any unusual file-related situations, such as corrupted files, or automatic file recovery, are noted in a log file for later examination.

Syntax:

LOG = { ON } { OFF }

Parameters:

ON
Set logging on either for the individual file or, if specified under the [XFH-DEFAULT] tag, for all files.
OFF
Do not set logging on.

Properties:

Default: ON
Parent topic: Configuration File Options
Related information
LOGFILENAME


LOGFILENAME

When the LOG option is active, the LOGFILENAME option specifies the name of the log file to produce.

Syntax:

LOGFILENAME = name

The log file lists any unusual file-related situations, such as corrupted files, or automatic file recovery. Contact technical support if you need more information regarding the contents of the file.

Parameters:

name
Name of the log file.

Properties:

Default: XFHLOG

Comments:

This option can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Use the program cobfhprint to create and display a text version of the log file:

cobfhprint filename
Parent topic: Configuration File Options


LSEQNAMETYPE

The LSEQNAMETYPE option determines if the FILESUFFIX option is used for line sequential files that do not explicitly specify a file extension.

Syntax:

LSEQNAMETYPE = { 0 } { 1 }

Parameters:

0
Do not apply the value of FILESUFFIX to line sequential files that do not explicitly specify a file extension.
1
Apply the value of FILESUFFIX to line sequential files that do not explicitly specify a file extension.

Properties:

Default: 0
Parent topic: Configuration File Options
Related reference
FILESUFFIX


LSFILETERM

The option controls the behavior of the File Handler upon encountering the EOF character x"1a" when reading line sequential files.

Syntax:

LSFILETERM = { ON } OFF

Parameters:

ON
Interpret x"1a" characters as EOF markers.
OFF
Ignore EOF characters and continue reading until the physical end of file.

Properties:

Default: OFF

Comments:

This option corresponds to bit h"10" of the fcd-flags-2 field in the File Control Description (FCD).

Parent topic: Configuration File Options


LSRECDELIM

The LSRECDELIM option specifies the characters to be used as the record delimiter in line sequential files.

Syntax:

LSRECDELIM = { 0A } { 0D0A }

Parameters:

0A
The hexadecimal character x"0A" is used as the record delimiter for line sequential files.
0D0A
The hexadecimal characters x"0D0A" are used as the record delimiter for line sequential files.

Properties:

Default: 0A .
Parent topic: Configuration File Options


MAINFRAMEPRINT

For those files using WRITE AFTER ADVANCING or WRITE BEFORE ADVANCING, the MAINFRAMEPRINT option determines whether to use mainframe printer file format (filetype 11).

Syntax:

MAINFRAMEPRINT = { ON } { OFF }

Parameters:

ON
Use mainframe printer file format.
OFF
Do not use mainframe printer file format.

Properties:

Default: OFF
Parent topic: Configuration File Options


NAMEOPTIONS

The NAMEOPTIONS option specifies whether the name you pass to the OPEN statement can contain File Handler options.

Syntax:

NAMEOPTIONS = { ON } { OFF }

Parameters:

ON
The name you pass to the OPEN statement can contain File Handler options enclosed in round or square brackets. For example:
fil1[PRINTER]
OFF
The name you pass to the OPEN statement cannot contain File Handler options.

Properties:

Default: OFF

Comments:

If set to OFF, the brackets and the characters they enclose are considered as part of the file name.

Note:
  • This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.
  • This parameter is provided for compatibility with older products - you should use it only if you require compatibility with Micro Focus Workbench V4.0.
Parent topic: Configuration File Options


NFSFILELOCK

The NFSFILELOCK option enables applications to detect record locks and file locks on UNIX NFS file systems.

Syntax:

NSFILELOCK = { ON } { OFF } { HP }

Parameters:

ON
Enables programs to detect record and file locks on UNIX NFS file systems.
OFF
Windows applications cannot detect record and file locks on UNIX NFS systems.
HP
Specify HP if you are accessing Hewlett-Packard systems.

Properties:

Default: OFF
Parent topic: Configuration File Options


NODESIZE

The NODESIZE option specifies the size of the index nodes to use for an indexed file.

Syntax:

NODESIZE = size_of_node

Parameters:

size_of_node
Use the following minimum NODESIZE values depending on the length of your keys:
Key Length in Bytes | Minimum NODESIZE Value in Bytes
Less than 51 | 512
51 through 100 | 1024
101 through 512 | 4096
513 through 4080 | 16384

Properties:

Default: The minimum NODESIZE value for the key length, except that for key lengths less than 50 bytes, the default is 1024.

Comments:

In most circumstances you should allow the File Handler to work out the appropriate default node size. However, if file size is an issue, smaller node sizes do result in a smaller index file, but you should be aware that they also increase processing time as the tree depth is greater.

Parent topic: Configuration File Options


NOSEQCHECK

The NOSEQCHECK option disables sequence-checking of keys in indexed files.

Setting this option ON enables records to be written in any order to indexed files opened in sequential access mode. Otherwise records must be written in ascending order of prime key.

Syntax:

NOSEQCHECK = { ON } { OFF }

Parameters:

ON
Do not check the sequence of prime keys when writing to an indexed file with ACCESS SEQUENTIAL.
OFF
Return status 21 if prime keys are written out of sequence to an indexed file with ACCESS SEQUENTIAL.

Properties:

Default: OFF

Comments:

Note:

Micro Focus strongly suggest that you control the order in which records are written to indexed files within the program itself, by using the ACCESS SEQUENTIAL or ACCESS DYNAMIC syntax, and avoid using the NOSEQCHECK configuration option.

Parent topic: Configuration File Options


OPENINPUTSHARED

The OPENINPUTSHARED option specifies whether files that you open for input, and for which you do not specify a LOCK MODE clause, can be shared by other users.

Syntax:

OPENINPUTSHARED = { ON } { OFF }

Parameters:

ON
Other users can have the file open for INPUT only.
OFF
The system behaves as if you are specifying LOCK MODE IS MANUAL for the file. That is, other users can have the file open for I-O, provided they specify a LOCK MODE for the file.

Properties:

Default: OFF
Parent topic: Configuration File Options


OSVSREWRITE

The OSVSREWRITE option specifies whether to permit the WRITE statement for sequential files that are open for output. If so, these WRITE statements behave exactly like REWRITE statements.

Syntax:

OSVSREWRITE = { ON } { OFF }

Parameters:

ON
Permit the WRITE statement for sequential files that are open for output.
OFF
Do not permit the WRITE statement for sequential files that are open for output.

Properties:

Default: OFF

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


READSEMA

The READSEMA option specifies whether the system attempts to gain a semaphore for shared files when I/O operations are performed that do not modify the file.

Syntax:

READSEMA = { ON } { OFF }

Parameters:

ON
Attempt to gain a semaphore for every file operation, including READ and START operations.
OFF
Do not attempt to gain a semaphore for shared files during operations such as READ and START.

Properties:

Default: OFF

Comments:

Where a file is being read by multiple users, to improve throughput set this parameter to OFF.

Parent topic: Configuration File Options


READTODELIM

The READTODELIM option specifies whether the file pointer is advanced to the next logical record in the file when reading in a record that is longer than the user data area. In these circumstances, the data record would effectively be truncated.

The option affects only line sequential files.

Syntax:

READTODELIM = { ON } { OFF }

Parameters:

ON
Records are truncated to the length of the user record area if necessary.
OFF
The file pointer is not advanced to the next logical record so one logical record might require several READs to consume it.

Properties:

Default: OFF
Parent topic: Configuration File Options


RELDATBUF

The RELDATBUF option determines the size of buffer used when accessing a file with organization RELATIVE.

Syntax:

RELDATBUF = { integer } { 0 }

Parameters:

integer
Round up the value that you enter to the next power of 2 that is greater or equal.
0
Do not use buffering.

Properties:

Default: 4096

Comments:

A non-zero value can be beneficial in the following circumstances:

  • While you are creating the file.
  • When most of the access to the file is sequential.

However, in other cases there is likely to be no performance gain. In fact, performance may be degraded.

Parent topic: Configuration File Options


RELNAMETYPE

The RELNAMETYPE option determines if the FILESUFFIX option is used for relative files that do not explicitly specify a file extension.

Syntax:

RELNAMETYPE = { 0 } { 1 }

Parameters:

0
Do not apply the value of FILESUFFIX to relative files that do not explicitly specify a file extension.
1
Apply the value of FILESUFFIX to line relative files that do not explicitly specify a file extension.

Properties:

Default: 0
Parent topic: Configuration File Options
Related reference
FILESUFFIX


RELRECDELIM

The RELRECDELIM option specifies the characters to be used as the record delimiter in fixed-length relative files.

Syntax:

RELRECDELIM = { 0A } { 0D0A }

Parameters:

0A
The hexadecimal character x"0A" is used as the record delimiter for fixed-length relative files.
0D0A
The hexadecimal characters x"0D0A" are used as the record delimiter for fixed-length relative files.

Properties:

Default: 0A.
Parent topic: Configuration File Options


RETRYLOCK

The RETRYLOCK option indicates whether you wish to retry a READ operation that fails because the record is locked.

Syntax:

RETRYLOCK = { ON } { OFF } { NOSTATUS } { integer }

Parameters:

ON
Retry the operation until no lock is encountered.
OFF
Do not attempt a retry.
NOSTATUS
Retry the operation for those files for which no status field is defined.
integer
Specify the number of attempts or the number of seconds for which you wish to retry the operation before a locked record status is returned. The RETRYTIME option controls the meaning of integer; for more information see the topic RETRYTIME.

Properties:

Default: OFF
Parent topic: Configuration File Options
Related information
RETRYTIME


RETRYOPEN

The RETRYOPEN option indicates whether you wish to retry an I/O operation that fails because the file is locked.

Syntax:

RETRYOPEN = { ON } { ON } { integer }

Parameters:

ON
Retry the operation until no lock is encountered.
OFF
Do not attempt a retry.
integer
Specify the number of attempts or the number of seconds for which you wish to retry the operation before a locked record status is returned. The RETRYTIME option controls the meaning of integer; for more information see the topic RETRYTIME

Properties:

Default: OFF
Parent topic: Configuration File Options
Related information
RETRYTIME


RETRYTIME

The RETRYTIME option specifies whether the integer given in the RETRYLOCK and RETRYOPEN options specifies the number of attempts or the number of seconds.

Syntax:

RETRYTIME = { ON } { OFF }

Parameters:

ON
The integer specifies the number of seconds.
OFF
The integer specifies the number of attempts.

Properties:

Default: OFF
Parent topic: Configuration File Options
Related information
RETRYLOCK
RETRYOPEN


RUNITLOCKDETECT

The RUNITLOCKDETECT option specifies whether the File Handler checks whether a record has been locked by a separate OPEN statement issued from within the same run unit.

Syntax:

RUNITLOCKDETECT = { ON } { OFF }

Parameters:

ON
Detect record locks.
OFF
Do not detect record locks.

Properties:

Default: ON

Comments:

Locks set within a given run unit are detected, even if RUNITLOCKDETECT is on, if this is supported by the operating system.

Parent topic: Configuration File Options


SEARCHONCREATE

The SEARCHONCREATE parameter determines whether the File Handler searches each specified directory on a multi-directory path for a file with the same name as the one being created. This option applies only to files which are opened with OPEN OUTPUT.

Syntax:

SEARCHONCREATE = { ON } { OFF }

Parameters:

ON
The path will be searched for the file and, if found, the directory where it is found will be used for the creation of the new file.
OFF
The file will be created in the first directory on the search path.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


SEQDATBUF

The SEQDATBUF option determines the size of buffer to use when accessing a file with organization SEQUENTIAL.

Syntax:

SEQDATBUF = integer

Parameters:

integer
Round up the value that you enter to the next power of 2. The minimum value is 4096.

Properties:

Default: 4096
Parent topic: Configuration File Options


SEQNAMETYPE

The SEQNAMETYPE option determines if the FILESUFFIX option is used for sequential files that do not explicitly specify a file extension.

Syntax:

SEQNAMETYPE = { 0 } { 1 }

Parameters:

0
Do not apply the value of FILESUFFIX to sequential files that do not explicitly specify a file extension.
1
Apply the value of FILESUFFIX to sequential files that do not explicitly specify a file extension.

Properties:

Default: 0
Parent topic: Configuration File Options
Related reference
FILESUFFIX


SKIPLOCK

The SKIPLOCK option specifies whether to advance the current record pointer when a locked record is encountered during a sequential READ.

Syntax:

SKIPLOCK = { ON } { OFF }

Parameters:

ON
Advance the current record pointer when a locked record is encountered.
OFF
Do not advance the current record pointer.

Properties:

Default: OFF
Parent topic: Configuration File Options


SPACEFILL

The SPACEFILL option determines whether to fill with spaces that part of the record area beyond the data that is read when performing READ operations on line sequential or line advancing files.

Syntax:

SPACEFILL = { ON } { OFF }

Parameters:

ON
Fill the area with spaces.
OFF
Do not fill the area with spaces.

Properties:

Default: ON
Parent topic: Configuration File Options


STARTUNLOCK

The STARTUNLOCK option determines whether a START operation will remove existing locks for files specified with single record locking; that is, without the WITH LOCK ON MULTIPLE RECORDS phrase.

Syntax:

STARTUNLOCK = { ON } { OFF }

Parameters:

ON
A START operation will clear any existing lock for files specified with single record locking.
OFF
A START operation will not clear any existing lock for files specified with single record locking.

Properties:

Default: OFF

Comments:

This option is provided only for compatibility. Micro Focus recommend you do not change it.

Parent topic: Configuration File Options


STRIPSPACE

The STRIPSPACE parameter determines whether to remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.

Syntax:

STRIPSPACE = { ON } { OFF }

Parameters:

ON
Remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.
OFF
Do not remove trailing space characters when performing WRITE or REWRITE operations on line sequential or line advancing files.

Properties:

Default: ON
Parent topic: Configuration File Options


SUPPRESSADV

The SUPPRESSADV option determines whether to ignore the ADVANCING phrase of the WRITE statement for record sequential files.

Syntax:

SUPPRESSADV = { ON } { OFF }

Parameters:

ON
Ignore the ADVANCING phrase of the WRITE statement for record sequential files.
OFF
Do not ignore the ADVANCING phrase of the WRITE statement for record sequential files.

Properties:

Default: OFF
Parent topic: Configuration File Options


TRACE

The TRACE option specifies whether Xfhtrace, the File Handler trace module, is enabled. The Xfhtrace module traces File Handler operations and logs all activity to a trace file. It is supplied to help you diagnose any problems you may have with COBOL files.

Syntax:

TRACE = { ON } { OFF }

Parameters:

ON
Set tracing on either for the individual file or, if specified under the [XFH-DEFAULT] tag, for all files.
OFF
Do not produce a trace file.

Properties:

Default: OFF
Parent topic: Configuration File Options


TRACEFILEEXTEND

The TRACEFILEEXTEND option determines whether to write trace information to the end of the current trace file, if the trace file already exists. This option has no effect if TRACE is OFF.

Syntax:

TRACEFILEEXTEND = { ON } { OFF }

Parameters:

ON
Extend existing trace file when File Handler is first invoked.
OFF
Overwrite existing trace file when File Handler is first invoked.

Properties:

Default: OFF

Comments:

This parameter can be set globally only, that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


TRACEFILENAME

The TRACEFILENAME option specifies the name of the trace file to produce when the TRACE option is active.

Syntax:

TRACEFILENAME = filename

Parameters:

filename
Name of the trace file.

Properties:

Default: XFHTRACE.XFH

Comments:

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


USEVSAMKEYDEFS

Use the keys defined in the catalog via the JCL and IDCAMS instead of the keys defined in the executing program.

Syntax:

USEVSAMKEYDEFS = { ON } { OFF }

Parameters:

ON
Use the catalog's key definitions.
OFF
Use executing program's key definitions.

Properties:

Default: ON
Parent topic: Configuration File Options


WRITELINE

The WRITELINE parameter determines whether mainframe or PC behavior is used for WRITE record.

Syntax:

WRITELINE = { ON } { OFF }

Parameters:

ON
Mainframe behavior is used for WRITE record.
OFF
PC behavior is used for WRITE record.

Properties:

Default: OFF

Comments:

Set WRITELINE=OFF if you want PC print behavior for WRITELINE when using mainframe dialects.

Parent topic: Configuration File Options


WRITETHRU

The WRITETHRU option determines whether modifications to a file are written out to disk immediately or buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.

Syntax:

WRITETHRU = { ON } { OFF }

Parameters:

ON
Write out all modifications to disk immediately.
OFF
Flush modifications later.

Properties:

Default: OFF

Comments:

You can obtain greater security, at the cost of significantly reduced performance, by setting this parameter to ON.

Parent topic: Configuration File Options


Operation Codes

  • Standard Operation Codes
  • Special Operation Codes
Parent topic: File Handling Reference


Standard Operation Codes

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid.

  • Standard Operation Codes - Overview
  • CLOSE
  • COMMIT
  • DELETE
  • DELETE FILE
  • OPEN
  • READ
  • REWRITE
  • ROLLBACK
  • START
  • STEP
  • UNLOCK
  • WRITE
Parent topic: Operation Codes


Standard Operation Codes - Overview

Standard operation codes contain x"FA" in the most significant byte. The least significant byte indicates the specific operation.

CLOSE | Terminates the processing of a file.
COMMIT | Releases all record locks in all files held by a run unit.
DELETE | Logically removes a record from a file.
DELETE FILE | Physically removes the specified file from the physical devices on which it resides.
OPEN | Initiates the processing of files. It also performs checking and/or writing of labels and other I/O operations.
READ | For sequential access, makes available the next or previous logical record from a file. For random access, makes available a specified record from a disk file.
ROLLBACK | Releases all record locks in all files held by a run unit.
START | Provides a basis for logical positioning in a relative or indexed file, for subsequent retrieval of records.
STEP | Steps to the next physical record.
UNLOCK | Releases all record locks held by a run unit on a named file.
WRITE | Writes a new record to a file.
REWRITE | Replaces an existing record.

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid, using the following key:

L | Line sequential
S | Record sequential (including vS)
R | Relative (including vR)
I | Indexed
vS | Record sequential variable format only
vR | Relative variable format only
Parent topic: Standard Operation Codes


CLOSE

Terminates the processing of files and reels/units with optional rewind and locking where appropriate. For record sequential files, the terms "reel" and "unit" are interchangeable; the treatment of sequential disk files is logically equivalent to the treatment of a file on tape or similar sequential media.

Opcode | Operation | File Type
80 | CLOSE | L S R I
81 | CLOSE WITH LOCK | L S R I
82 | CLOSE WITH NO REWIND | L S
84 | CLOSE REEL/UNIT | L S
85 | CLOSE REEL/UNIT FOR REMOVAL | L S
86 | CLOSE REEL/UNIT WITH NO REWIND | L S

Input Fields

None

Output Fields

fcd-file status File status
Parent topic: Standard Operation Codes


COMMIT

Releases all record locks in all files held by this run unit.

Opcode | Operation | File Types
DC | COMMIT (Unlock all files) | L S R I

Input Fields

None

Output Fields

None

Comments

This operation code requires an FCD for one of the files, but it can be completely empty except for fcd-version specifiying whether FCD2 or FCD3 is in use.

Parent topic: Standard Operation Codes


DELETE

Logically removes a record from a disk file.

Opcode | Operation | File Types
F7 | DELETE | vS R I

Input Fields

fcd-relative-key | Relative key of record to remove (R)
fcd-record-address | Pointer to the record area of the record to remove (I)

Output Fields

fcd-file status File status
Parent topic: Standard Operation Codes


DELETE FILE

Physically removes the specified file from the physical devices on which it resides.

Opcode | Operation | File Types
F8 | DELETE FILE | L S R I

Input Fields

Filename area |
fcd-organization | File organization
fcd-name-length | Filename length
fcd-file-format | File format
fcd-filename-address | Pointer to the filename area

Output Fields

fcd-file status File status
Parent topic: Standard Operation Codes


OPEN

Initiates the processing of a file. It also performs checking and writing of labels and other I/O operations.

Opcode | Operation | File Types
00 | OPEN INPUT | L S R I
01 | OPEN OUTPUT | L S R I
02 | OPEN I-O | L S R I
03 | OPEN EXTEND | L S R I
04 | OPEN INPUT WITH NO REWIND | L S
05 | OPEN OUTPUT WITH NO REWIND | L S
08 | OPEN INPUT REVERSED | L S

Input Fields

Filename area |
Key definition block |
fcd-organization | File organization
fcd-access-mode | Access mode
fcd-open-mode | Open mode
fcd-name-length | Length of filename
fcd-lock-mode | Lock mode flags
fcd-other-flags | Other flags
fcd-file-format | File format
fcd-max-rec-length | Maximum record length
fcd-recording-mode | Recording mode
fcd-min-rec-length | Minimum record length
fcd-filename-address | Pointer to the filename area
fcd-key-def-address | Pointer to the key definition block (I)
fcd-data-compress | Data compression
fcd-locktypes | Type of file locks

Output Fields

fcd-file status | File status
fcd-open-mode | Open mode
fcd-handle | Pointer to the file; use for all subsequent accesses to this file

Comments

You must have set up a key definition block for this file if it is an indexed file.

You can assign several FCDs to the same physical file and have them all open at the same time. The operating system counts it as just one open file. The physical file is not closed until every logical file assigned to it has been closed.

Parent topic: Standard Operation Codes


READ

For sequential access, makes available the next or previous logical record from a file. For random access, makes available a specified record from a disk file.

Opcode | Operation | File Types
8D | READ(sequential) WITH NO LOCK | L S R I
D8 | READ (sequential) WITH LOCK | L S R I
D9 | READ (sequential) WITH KEPT LOCK | L S R I
F5 | READ (sequential) | L S R I
8C | READ PREVIOUS WITH NO LOCK | R I
DE | READ PREVIOUS WITH LOCK | R I
DF | READ PREVIOUS WITH KEPT LOCK | R I
F9 | READ PREVIOUS | R I
8E | READ (random) WITH NO LOCK | R I
DA | READ (random) WITH LOCK | R I
DB | READ (random) WITH KEPT LOCK | R I
F6 | READ (random) | R I
8F | READ (direct) WITH NO LOCK | L S R I
D6 | READ (direct) WITH LOCK | L S R I
D7 | READ (direct) WITH KEPT LOCK | L S R I
C9 | READ (direct) | L S R I
F1 | READ (position) | L S R I

Input Fields

fcd-relative-key | Relative record number (R) if READ random or direct
fcd-key-id | Key identifier (I)
fcd-record-address | Pointer to the record area

Output Fields

fcd-file status | File status
fcd-current-rec-len | Current record length
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Standard Operation Codes


REWRITE

Replaces an existing record in a file.

Opcode | Operation | File Types
F4 | REWRITE | L S R I

Input Fields

cfd-relative-key | Relative record number (R)
fcd-current-rec-len | Current record length
fcd-record-address | Pointer to the record area

Output Fields

fcd-file-status | File status
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Standard Operation Codes


ROLLBACK

Releases all record locks in all files held by this run unit.

Opcode | Operation | File Types
DD | ROLLBACK (unlocks all files) | L S R I

Input Fields

None

Output Fields

None

Comments

This operation code requires an FCD for one of the files, but it can be completely empty except for fcd-version specifiying whether FCD2 or FCD3 is in use.

Parent topic: Standard Operation Codes


START

Provides a basis for logical positioning in a relative or indexed file, for subsequent retrieval of records.

Opcode | Operation | File Types
E8 | START equal to full length prime key | R I
E9 | START equal to (any key/record number) | R I
EA | START greater than (>) | R I
EB | START not less than (>=) | R I
FE | START less than (<) | R I
FF | START less than or equal to (<=) | R I

Input Fields

fcd-relative key | Relative record number (R)
fcd-key id | Key identifier (I)
fcd-key-length | Effective key length (I)
fcd-record-address | Pointer to the record area

Output Fields

fcd-file status File status
Parent topic: Standard Operation Codes


STEP

Steps to the next, previous, first or last physical record in the file . This operation enables very fast access to a record.

Opcode | Operation | File Types
90 | STEP NEXT WITH NO LOCK | L S R I
91 | STEP PREVIOUS WITH NO LOCK | L S R I
92 | STEP FIRST WITH NO LOCK | L S R I
93 | STEP LAST WITH NO LOCK | L S R I
CA | STEP NEXT | L S R I
CB | STEP PREVIOUS | L S R I
CC | STEP FIRST | L S R I
CD | STEP LAST | L S R I
CE | STEP LAST WITH LOCK | L S R I
CF | STEP LAST WITH KEPT LOCK | L S R I
D0 | STEP FIRST WITH LOCK | L S R I
D1 | STEP FIRST WITH KEPT LOCK | L S R I
D2 | STEP PREVIOUS WITH LOCK | L S R I
D3 | STEP PREVIOUS WITH KEPT LOCK | L S R I
D4 | STEP NEXT WITH LOCK | L S R I
D5 | STEP NEXT WITH KEPT LOCK | L S R I

Input Fields

fcd-record-address Pointer to the record area

Output Fields

fcd-file-status File status

Comments

STEP operations are a method of sequentially retrieving records in a relative or indexed file without having to read via a key or relative record number. Generally, this is a faster method of accessing data in the file.

A STEP NEXT operation returns the record that is physically stored immediately after the one that was last retrieved in the file (either by a STEP or READ operation).

A STEP PREVIOUS operation returns the record that is physically stored immediately before the one that was last retrieved in the file (either by a STEP or READ operation).

A STEP FIRST operation returns the record at the beginning of the file.

A STEP LAST operation returns the record at the end of the file.

If you are using relative byte addressing and you have specified that the current record pointer should be updated to the record you have just accessed, STEP operations are relative to this new position.

The relative byte address is returned on every STEP operation, so if you need to update the current record pointer to the record just retrieved, you can use the READ (direct) operation using the address returned.

Note:

The current record pointer is not affected by STEP operations.

Parent topic: Standard Operation Codes


UNLOCK

Releases all record locks held by the run unit on a named file.

Opcode | Operation | File Types
0E | UNLOCK | L S R I

Input Fields

None

Output Fields

fcd-file-status File status
Parent topic: Standard Operation Codes


WRITE

Writes a new record to a file.

For sequential files, it can also be used for vertical positioning of lines in a logical page.

Opcode | Operation | File Types
E1 | WRITE BEFORE | L S
E2 | WRITE AFTER | L S
E3 | WRITE BEFORE TAB | L S
E4 | WRITE AFTER TAB | L S
E5 | WRITE BEFORE PAGE | L S
E6 | WRITE AFTER PAGE | L S
EC | WRITE BEFORE mnemonic-name | S
ED | WRITE AFTER mnemonic-name | S
F3 | WRITE | L S R I

Input Fields

cfd-relative-key | Relative record number (R)
fcd-current-rec-len | Current record length
fcd-line-count | Line count (WRITE only) (S)
fcd-record-address | Pointer to the record area

Output Fields

fcd-file-status | File status
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Standard Operation Codes


Special Operation Codes

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid.

  • Special Operation Codes - Overview
  • File Information
  • Create Index File
  • Get Next Record
  • Add Key Value
  • Re-index File
  • Flush File
  • Unlock Record
Parent topic: Operation Codes


Special Operation Codes - Overview

Special operation codes contain x"00" in the most significant byte. The least significant byte indicates the specific operation.

File Information | Returns general file information for all file organizations with headers and, for indexed files, information on the file keys in the form of the Key Definition Block.
Get Next Record | Gets the next physical record from the data file part of an indexed file.
Add Key Value | Adds a key value to the index file part of an indexed file.
Re-index File | Re-indexes the file using a supplied key definition block.
Flush File | Flushes all data for a specific file to disk.
Unlock Record | Unlocks a specific record in a file.

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid, using the following key:

L | Line sequential
S | Record sequential (including vS)
R | Relative (including vR)
I | Indexed
vS | Record sequential variable format only
vR | Relative variable format only
Parent topic: Special Operation Codes


File Information

Returns general file information for all file organizations with headers and, for indexed files, information on the file keys in the form of the key definition block.

Opcode | Operation | File Types
06 | Return file information | I vS vR

Input Fields

fcd-organization | File organization (can be x"FF")
fcd-name-length | Length of filename
fcd-filename-address | Pointer to the filename area
fcd-key-def-address | Pointer to the key definition block (I)

Output Fields

Key definition block (I) |
fcd-file-status | File status
fcd-organization | File organization
fcd-file-format | File format
fcd-max-rec-length | Maximum record length
fcd-recording-mode | Recording mode
fcd-min-rec-length | Minimum record length
fcd-reladdr-offset or fcd-reladdr-big | File size
fcd-data-compress | Data compression routine

It is your responsibility to ensure that you have enough space allocated for the key definition block to hold all the information returned. Failure to allocate enough space causes corruption of some data areas.

For variable-length sequential files and variable-length relative files, no key definition information exists.

If you can set the organization byte of the FCD to x"FF" before using this operation code, an attempt is made to determine the file type and return with the relevant information set. This mode of operation is not recommended if you use any fixed-length sequential files as it might be impossible to determine the difference between the first record of a fixed-length sequential file and the header of a variable-length sequential file. If the file type cannot be determined, the error code 9/161 is returned.

Parent topic: Special Operation Codes


Create Index File

Creates a new .idx file, containing only header information for the file to allow new indexes to be added.

Opcode | Operation | File Types
07 | Open new index | I

Input Fields

As OPEN.

Output Fields

As OPEN

Parent topic: Special Operation Codes


Get Next Record

Gets the next physical record from the data file part of an indexed file.

Opcode | Operation | File Types
08 | Get next record | I

Input Fields

fcd-record-address Pointer to the record area

Output Fields

fcd-file-status | File status
fcd-current-rec-len | Current record length
fcd-reladdr-offset or fcd-reladdr-big | Relative byte address
Parent topic: Special Operation Codes


Add Key Value

Adds a key value to the index file part of an indexed file.

Opcode | Operation | File Types
09 | Add key value | I

Input Fields

fcd-key-id | Key identifier
fcd-record-address | Pointer to the record area

Output Fields

fcd-file-status File status
Parent topic: Special Operation Codes


Re-index File

Re-indexes the file using a supplied key definition block.

Opcode | Operation | File Types
0B | Re-index file | I

Input Fields

Offset 64 Pointer to key definition block.

Output Fields

None
Parent topic: Special Operation Codes


Flush File

Flushes all data for a specific file to disk.

Opcode | Operation | File Types
0C | Flush File | L S R I

Input Fields

None

Output Fields

fcd-file-status File status
Parent topic: Special Operation Codes


Unlock Record

Unlocks a specific record in a file.

Opcode | Operation | File Types
0F | Unlock record | I

Input Fields

fcd-record-address Pointer to the record area

Output Fields

fcd-file-status File status
Parent topic: Special Operation Codes


File Status

  • File Status Codes
  • Extended File Status Codes
  • Microsoft COBOL V2 File Status Codes
Parent topic: File Handling Reference


File Status Codes

00
Successful completion.
02
Indexed files only. One of two possibilities: For a READ statement, the key value for the current key is equal to the value of that same key in the next record in the current key of reference. For a WRITE or REWRITE statement, the record just written created a duplicate key value for at least one alternate record key for which duplicates are allowed.
04
The length of the record being processed does not conform to the fixed file attributes for that file.
05
The referenced optional file is not present at the time the OPEN statement is executed.
07
Sequential files only. For an OPEN or CLOSE statement with the REEL/UNIT phrase the referenced file is a non-reel/unit medium.
10
No next logical record exists. You have reached the end of the file.
14
Relative files only. The number of significant digits in the relative record number is larger than the size of the relative key data item described for that file.
21
Sequentially accessed files only. Indicates a sequence error. The ascending key requirements of successive record key values has been violated, or, the prime record key value has been changed by a COBOL program between successful execution of a READ statement and execution of the next REWRITE statement for that file.
22
Indexed and relative files only. Indicates a duplicate key condition. Attempt has been made to store a record that would create a duplicate key in the indexed or relative file OR a duplicate alternate record key that does not allow duplicates.
23
Indicates no record found. An attempt has been made to access a record, identified by a key, and that record does not exist in the file. Alternatively a START or READ operation has been tried on an optional input file that is not present.
24
Relative and indexed files only. Indicates a boundary violation arising from one of the following conditions: an attempt is made to write beyond the externally defined boundaries of a file; a sequential WRITE operation has been tried on a relative file, but the number of significant digits in the relative record number is larger than the size of the relative key data item described for the file.
30
The I/O statement was unsuccessfully executed as the result of a boundary violation for a sequential file or as the result of an I/O error, such as a data check parity error, or a transmission error.
34
The I/O statement failed because of a boundary violation. This condition indicates that an attempt has been made to write beyond the externally defined boundaries of a sequential file.
35
An OPEN operation with the I-O, INPUT, or EXTEND phrases has been tried on a non-OPTIONAL file that is not present.
37
An OPEN operation has been tried on a file which does not support the open mode specified in the OPEN statement.
38
An OPEN operation has been tried on a file previously closed with a lock.
39
A conflict has been detected between the fixed file attributes and the attributes specified for that file in the program.
41
An OPEN operation has been tried on a file already opened.
42
A CLOSE operation has been tried on a file already clsoed.
43
Files in sequential access mode. The last I/O statement executed for the file, before the execution of a DELETE or REWRITE statement, was not a READ statement.
44
A boundary violation exists. Possible violations are:
  • An attempt has been made to WRITE or REWRITE a record that is larger than the largest, or smaller than the smallest record allowed by the RECORD IS VARYING clause of the associated file.
  • An attempt has been made to REWRITE a record to a file, and the record is not the same size as the record being replaced.
46
A sequential READ operation has been tried on a file open in the INPUT or I-O mode but no valid next record has been established.
47
A READ or START operation has been tried on a file not opened INPUT or I-O.
48
A WRITE operation has been tried on a file not opened in the OUTPUT, I-O, or EXTEND mode, or on a file open I-O in the sequential access mode.
49
A DELETE or REWRITE operation has been tried on a file that is not opened I-O.
Parent topic: File Status


Extended File Status Codes

When using ANSI'74 or ANSI'85 file status codes, run-time system returns extended file status codes if the extended file status is more specific.

Extended file status codes are of the form:

9/nnn

where nnn is a numeric value that is the same as the numeric value of the corresponding run-time system error. For example, if an extended file status code of 9/029 is returned, run-time system error COBRT029 (Attempt to delete open file) provides more information about the cause.

Parent topic: File Status


Microsoft COBOL V2 File Status Codes

Status Key 1 | Status Key 2 | Description
0 | 0 | Successful completion.
 | 2 | Duplicate key and duplicates are allowed.
1 | 0 | End of file.
2 | 1 | Sequence error in writing sequential access file.
 | 2 | Duplicate key and duplicates are not allowed.
 | 3 | Key not found.
 | 4 | Disk space full.
3 | 0 | Permanent error or file not found.
 | 4 | Disk space full.
9 | 1 | File structure error.
 | 4 | File or record locked.
 | 5 | Indexed file system not available.
Parent topic: File Status


MFSORT and MFJSORT Utilities

  • Introduction
  • Invoking Mfsort
  • Creating a Statistics Report
  • Example Commands
  • Error Messages
Parent topic: File Handling Reference


Introduction

This COBOL system provides the following methods of sorting and merging files:

Sorting Method | Description
The run-time system COBOL sort module | The default module that executes a SORT statement in your COBOL program. It can also be called directly using the CALL statement.
MFSORT utility | A utility that you can invoke from the command line, which enables you to sort and merge data files.
MFJSORT utility | An emulator of IBM’s DFSORT and ICETOOL utilities and SYNCSORT, which supports many of their major functions .
Note: MFJSORT and MFSORT are updated with new features on a regular basis but they do not offer a complete emulation of third-party sort utilities. If there are particular features that you need to use, please contact SupportLine to establish if they are available in MFJSORT or MFSORT.
Parent topic: MFSORT and MFJSORT Utilities
Related information
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages


Invoking Mfsort

You can invoke mfsort from the command line in one of the following ways:

mfsort instructions
mfsort take filename

where the parameters are:

Parameter Description
instructions Mfsort instructions.
When specifying instructions on the command line:
  • The maximum length of the mfsort command is 1024 characters. Characters after this limit are ignored, and if this truncation causes an invalid command, an error is produced.
  • Allow the shell to pass through special characters such as parentheses or comment characters (*) in one of the following ways:
    • Use quotes """" to enclose parentheses
    • Place an escape character \ directly in front of a parenthesis or a comment character
filename A text file containing mfsort instructions. See the section Instructions. Use this method if you need to specify a lot of instructions.

This file must be a line sequential file, and the first 256 characters are processed as the command line. If you exceed this limit, characters after this are processed separately, if they are valid, which may result in undesired sort results. If this truncation causes an invalid/incomplete command, an error is produced.

  • Instructions
Parent topic: MFSORT and MFJSORT Utilities
Related information
Introduction
Creating a Statistics Report
Example Commands
Error Messages
Instructions


Instructions

The following is a list of valid mfsort instructions:

Instruction | Meaning
* | The rest of the line is treated as a comment. This is useful if you are supplying instructions via a text file as you can add comments to the file which explain the purpose of each instruction.
CHAR-EBCDIC | EBCDIC data. CHAR-EBCDIC must precede all SORT, MERGE, USE or GIVE instructions.
SIGN-EBCDIC | Numeric DISPLAY items with included signs are interpreted according to the EBCDIC convention. SIGN-EBCDIC is not required when CHAR-EBCDIC is specified; it is required for data that is otherwise ASCII, such as when the program which created the data was compiled with the SIGN"EBCDIC" Compiler directive. SIGN-EBCDIC must precede all SORT, MERGE, USE or GIVE instructions.
SORT-EBCDIC | Record-sequential ASCII files are sorted in EBCDIC order. Important: SORT-EBCDIC cannot sort files that have keys containing non-printable characters.
SORT/MERGE | These instructions specify either a sort or a merge option and must be followed by a FIELDS instruction specifying the field(s) to be used. The FIELDS instruction may optionally be followed by a RECORD instruction specifying the record size and format of the workfile. SORT and MERGE are mutually exclusive.
FIELDS (instructions) | The fields on which the file is to be sorted or merged. See the section Fields Instruction.
RECORD definition | Record size and format. A RECORD instruction can be used to specify these details for the workfile, input file(s) and output file(s). See the section RECORD Instruction.
USE input-file | Each USE instruction specifies an input file. You must specify all USE instructions before any GIVE instructions. See the section Defining Input and Output Files.
GIVE output-file | Each GIVE instruction specifies an output file. See the section Defining Input and Output Files.
INCLUDE/OMIT | Specifies conditions in which records will be included or omitted from the sort process. For details, see the IBM documentation to be found at . INCLUDE and OMIT are mutually exclusive.
INREC | Reformats records before the SORT/MERGE process.
OUTREC | Reformats records following the SORT/MERGE process.
MODS | Specifies external procedures (user exits) that are executed, each time a record is released to or returned from the SORT/MERGE process. This implementation supports the E15 and E35 user exits.
SUM | Specifies that records with the same key value are returned as a single record. Optionally, a field may be specified to accumulate totals for all records with equal keys. The SUM operation can be done for the following control field types:
OUTFIL | This is used to specify complex editing and reporting to one or more output files. Each output file should be specified using a GIVE command. Otherwise, OUTFIL works as described in the IBM documentation to be found at .
OPTION | This can be used to specify various options. One of these options is COPY which results in records being copied, rather than sorted, to the output file.
  • FIELDS Instruction
  • Defining Input and Output Files
Parent topic: Invoking Mfsort
Related information
Invoking Mfsort
Fields Instruction
RECORD Instruction
Defining Input and Output Files


FIELDS Instruction

A SORT or MERGE instruction must be followed by a FIELDS instruction which specifies the fields on which the input file is to be sorted or merged.

A fields instruction takes the following form:

fields({start,length,type,order},...)

where the parameters are:

Parameter | Description
start | The starting position of the field in the record, counting in bytes from 1
length | The length of the field (bytes)
type | The type of data in the field. See the section Field Types .
order | The ordering of output, which can be either of: A - ascending D - descending

You can specify up to 100 fields by repeating the parameter set (start, length, type and order). Use commas to separate the parameters and the parameter sets.

  • Field Types
Parent topic: Instructions


Field Types

The following is a list of some of the available field types:

Field Type | Definition
AQ | Character with alternate collating sequence.
BI | COMP
C5 | COMP-5
C6 | COMP-6
CH | PIC X DISPLAY
CX | COMP-X
FL | Floating point, signed.
FS/CSF | Signed numeric, with optional leading floating sign.
LI/OL/CLO | PIC S9 LEADING INCLUDED
LS/CSL | PIC S9 LEADING SEPARATE
NU | PIC 9 DISPLAY
PD | PIC S9 COMP-3
PD0 | Packed decimal with first semi-byte and sign semi-byte ignored.
SB/FI | PIC S9 COMP
S5 | S9 COMP-5
SS | Substring. Used in conditions only.
TS/CST | PIC S9 TRAILING SEPARATE
TI/ZD/OT/CTO | PIC S9 TRAILING INCLUDED
Y2B | Two-digit, one-byte binary year data.
Y2C/Y2Z | Two-digit, two-byte year data, with optional trailing included sign. PIC 99 or PIC S99.
Y2D | Two-digit, one-byte packed decimal year data. PIC 99 COMP-6.
Y2P | Two-digit, two-byte packed decimal year data. PIC 99 COMP-3.
Y2S | Two-digit, two-byte character year data with special indicators. Binary zeros, blanks and binary ones are treated as special cases.
Y2T | Full date format, yyx...
Y2U | Full date format, yyx..., COMP-3.
Y2V | Full date format, yyx..., COMP-3. Ignores first semi-byte.
Y2W | Full date format, x...yy.
Y2X | Full date format, x...yy, COMP-3.
Y2Y | Full date format, x...yy, COMP-3. Ignores first semi-byte.

You can find other field types defined in the IBM documentation at SORT Control Statement.

Suppose that golf.dat is a relative file defined in a COBOL program as follows:

 file-control.
     select members-file
         assign to "/home/user/workarea/golf.dat"
         organization is relative
         access mode is random
         relative key is relative-key.
 data division.
 file section.
 fd members-file
     record contains 28 characters.
 01 members-record.
     03 members-number pic 9(6).
     03 members-lname pic x(10).
     03 members-fname pic x(10).
     03 members-handicap pic 9(2).

You can then use the following mfsort command to sort the file golf.dat on the field containing the membership number in ascending order:

mfsort sort fields(1,6,nu,a)
   use golf.dat record f,28 org rl
   give members.dat

The sorted version of the file is written to the file members.dat.

Parent topic: FIELDS Instruction


Defining Input and Output Files

You need to give instructions to define both the input and output files:

File Instructions
Input
USE input-file [record definition]
   [org organization] [key structure]
Output
GIVE output-file [record definition]
   [org organization] [key structure]

Notes:

  • For input files that are either variable length or indexed files, you do not need to specify RECORD, ORG or KEYcommands as the file characteristics can be deduced from the file itself.
  • If you omit any of the above instructions, the last specified values are used. Therefore, you need only specify values for the first file if the input and output files are all of the same type and format.
  • If the first file is variable length or indexed, you do not need to specify any of the values.
  • You can use embedded library names and environment variables when you specify input and output files, in the same way as you can when you specify them in ASSIGN clauses; for more information see the sections Library Names in Paths and Filename Mapping in the chapter Filenames.
  • You can redirect the output file generated by MFSORT to another filename as follows:
    • If you do not use the SYSOUT environment variable, it is written to a file named SYSOUT.
    • If you do specify the SYSOUT environment variable, you specify the filename to be written to.
  • RECORD Instruction
  • ORG Instruction
  • KEY Instruction
Parent topic: Instructions


RECORD Instruction

You use the RECORD instruction to specify the format and length of records in the:

  • Sort work file
  • Input and output files when the instruction follows the associated USE or GIVE instruction

The RECORD instruction takes the following form:

RECORD format,rec-len,max-len

where the parameters are:

Parameter | Description
format | The record format, one of: F - fixed-length records of length rec-len V - variable-length records with a minimum length of rec-len and a maximum length of max-len
rec-len | If format is set to F, the record length If format is set to V, the minimum record length
max-len | If format is set to V, the maximum record length

If you do not specify a RECORD instruction for the sort workfile, the format defaults to fixed record format, with the record size equal to the largest record specified in the USE or GIVE instructions.

You do not need to specify a RECORD instruction for input files that are either variable length or indexed files as the file characteristics can be deduced from the file itself.

You must use a RECORD instruction if the record size is greater than 256.

If you do not specify a max-len for a line sequential input file, mfsort assumes 256. If you exceed this, the output file will have the input records split into several records.

Parent topic: Defining Input and Output Files


ORG Instruction

The ORG instruction specifies the file organization, and can be one of:

ORG Instruction | File Organization
IX | indexed
RL | relative
SQ | sequential (default value)
LS | line sequential

You do not need to specify an ORG instruction for input files that are either variable length or indexed files as the file characteristics can be deduced from the file itself.

Parent topic: Defining Input and Output Files


KEY Instruction

The KEY instruction specifies the key structure for an indexed file. It is used when an output file is indexed and its key structure is not the same as that of the indexed input file.

The format of the KEY instruction is:

KEY ({start,length,ixkey},...)

where the parameters are:

start
The starting position of the key in a record, counting in bytes from 1
length
The number of bytes in the key
ixkey
One of:
P
Primary key (this must always be defined first)
A
Alternate key
AD
Alternate key with duplicates
C
Component of the last-specified primary or alternate key

You can repeat the KEY instruction as often as required to describe the entire key structure. Use commas to separate the parameters and parameter sets (start, length, ixkey).

You must define the keys in order of importance with the primary key first, followed by all its components if it is split, then the first alternate key and all of its components and so on.

The following example defines three keys:

KEY (4,5,p,10,5,c,20,2,ad,40,2,a,46,10,c)

where:

4,5,p,10,5,c | represents the first primary key which is split. Its first component starts at character position 4 with a length of 5 bytes and its second component starts at character position 10 with a length of 5 bytes.
20,2,ad | represents the second (alternate) key which can have duplicates and starts at character position 20 with a length of 2 bytes
40,2,a,46,10,c | represents the third key. This is a split alternate key, with the first component starting at character position 40 with a length of 2 bytes and the second component starting at character position 46 with a length of 10 bytes.
Parent topic: Defining Input and Output Files


Creating a Statistics Report

There are two ways in which you can produce a statistics report:

  • If you are not running under mainframe emulation, you can create a statistical report by using the MFJSTATS environment variable. For more information, see the section MFJSTATS in the appendix Environment Variables in your User's Guide.
  • If you are running under mainframe emulation, see the section Sort/Merge Operations (MFJSORT) in the chapter Utility Programs of your Mainframe Subsystem Support Developer's Guide for more information.
Parent topic: MFSORT and MFJSORT Utilities
Related information
Introduction
Invoking Mfsort
Example Commands
Error Messages


Example Commands

This section gives some examples of mfsort commands and jobstreams.

You may find it helpful to refer to the Examples of DFSORT Job Streams section of your DFSORT Application Programming Guide.

  • Sorting Using More Than One File
  • Single File Sort Using INCLUDE and a Sub-string Comparison
  • Single File Sort Using Environment Variables
  • Transforming Records Using OUTREC
  • Sort Using OUTFIL for Complex Reporting
Parent topic: MFSORT and MFJSORT Utilities
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Error Messages


Sorting Using More Than One File

Imagine four indexed files (north.dat, south.dat, east.dat and west.dat) which contain for the north, south, east and west of the country the scores achieved by members of a national organisation in a national competition. The COBOL syntax used to define north.dat is shown below:

 file-control.
     select idxfile assign to "north.dat"
         organization is indexed
         record key is member-id.
 data division.
 file section.
 fd idxfile
     record contains 39 characters.
 01 idxfile-record.
     03 member-id  pic 9(6).
     03 surname    pic x(15).
     03 first-name pic x(15).
     03 score      pic 9(3).

Each of the other files has been created in the same way and the results of the competition have been entered in the files. The following examples use these files.

  • Character Sort in Ascending Order
  • Numeric Sort in Descending Order
  • Omitting Records
Parent topic: Example Commands


Character Sort in Ascending Order

The following mfsort commands takes all of the records from each of the four files, sorts them on the member's surname in ascending order and outputs the result to the relative file members.dat:

mfsort sort fields(7,15,ch,a)
   use north.dat
   use south.dat
   use east.dat
   use west.dat
   give members.dat org rl
Parent topic: Sorting Using More Than One File


Numeric Sort in Descending Order

The following mfsort command takes each of the four files, sorts them on the member's score (highest score first) and outputs the result to the relative file scores.dat:

mfsort sort fields(37,3,nu,d)
   use north.dat
   use south.dat
   use east.dat
   use west.dat
   give scores.dat org rl
Parent topic: Sorting Using More Than One File


Omitting Records

The following mfsort command takes each of the four files, sorts them on the membership number (which is the primary key) and outputs the result to the indexed file national.dat. All records for which the score field is less than 20 are omitted:

mfsort sort fields(1,6,nu,a)
   use north.dat
   use south.dat
   use east.dat
   use west.dat
   give national.dat
   omit cond (37,3,nu,lt,20)
Parent topic: Sorting Using More Than One File


Single File Sort Using INCLUDE and a Sub-string Comparison

The following mfsort command takes a line sequential file, sortin.dat and sorts its records on a character field starting at position 11 with a length of 4 bytes. The results are output to the file sortout.dat which will include only records for which the sub-string, starting at position 15 of length 3 bytes, is equal to any three consecutive characters in the string 'J69,L92,J82'.

mfsort sort fields=(11,4,ch,a)
   use sortin.dat org ls record (f 80)
   give sortout.dat
   include cond=(15,3,ss,eq,c'J69,L92,J82')
Parent topic: Example Commands


Single File Sort Using Environment Variables

The following mfsort command takes a text file, unsorted.txt and a file a.1, sorts its records in ascending order, and outputs the result to the file sorted.txt.

set $infile=unsorted.txt
set $outfile=sorted.txt

mfsort take a.1

where unsorted. txt contains:

BBBBBBBBBBBBBBBBBBBB
CCCCCCCCCCCCCCCCCCCC
AAAAAAAAAAAAAAAAAAAA

and a.1 contains:

use $infile org LS
sort
give $outfile
Parent topic: Example Commands


Transforming Records Using OUTREC

The following mfsort command transforms records containing a field of format cyymmdd to the format yyymmdd.

Sort C'cyymmdd'
     SORT FIELDS=(1,7,BI,A)        * sort C'cyymmdd'
     use mfs110a.in org ls record (f 40)
    * Transform C'cyymmdd' to C'yyyymmdd'
     OUTFIL OUTREC=(1,1,CHANGE=(2, * change C'c' as follows:
                      C'0',C'19',  *   C'0' to C'19'
                      C'1',C'20',  *   C'1' to C'20'
                      C'2',C'21'), *   C'2' to C'21'
                      NOMATCH=(C'99')
                    2,6)           * copy C'yymmdd'

     give sortout.dat
Parent topic: Example Commands


Sort Using OUTFIL for Complex Reporting

The following is an example of how to use the OUTFIL command to produce a complex report, in this case a Profit and Loss report for one of four divisions. The input file, mfs121a.dat is sorted on the first two fields and only records from the western region are output. The SECTIONS instruction produces a page throw when the field starting in position 3, length 10 bytes changes. The following shows:

  • The input data
  • The mfsort command
  • The resultant output
  • Input Data
  • Mfsort Command
  • Output
Parent topic: Example Commands


Input Data

  Chips        San Martin     0088902203 West
  Chips        Oakland        0023412432 West
  Chips        San Jose       0123213335 West
  Ice Cream    Marin          0054234123 West
  Chips        Gilroy         0055484342 West
  Ice Cream    Napa           0085734283 West
  Pretzels     San Jose       0123488534 West
  Ice Cream    San Francisco  0092231245 West
  Chips        San Francisco  000324343q West
  Chips        San Jose       0123213335 South
  Ice Cream    San Martin     0100346730 West
  Pretzels     Marin          0534332344 West
  Chips        Gilroy         0055484342 South
  Chips        Morgan Hill    0098732232 West
  Pretzels     Morgan Hill    0084384340 West
  Ice Cream    San Jose       000002345u West
  Pretzels     Napa           0531234856 West
  Chips        Oakland        0023412432 South
  Pretzels     San Martin     000023438r West
  Chips        Los Angeles    000223401t West
  Ice Cream    Marin          0054234123 South
  Pretzels     San Francisco  0541230005 West
  Ice Cream    Napa           0085734283 South
  Pretzels     San Jose       0123488534 South
  Ice Cream    San Francisco  0092231245 South
  Chips        San Francisco  000324343q South
  Ice Cream    San Martin     0100346730 South
  Pretzels     Marin          0534332344 South
  Chips        Morgan Hill    0098732232 South
  Pretzels     Morgan Hill    0084384340 South
  Ice Cream    San Jose       000002345u South
  Pretzels     Napa           0531234856 South
  Pretzels     San Martin     000023438r South
  Chips        Los Angeles    0002234014 South
  Pretzels     San Francisco  0541230005 South
Parent topic: Sort Using OUTFIL for Complex Reporting
Related information
Mfsort Command
Output


Mfsort Command

SORT FIELDS=(3,10,A,16,13,A),FORMAT=CH

  use mfs121a.dat  org ls record (f 80)
  OUTFIL
   INCLUDE=(42,6,CH,EQ,C'West'),
   HEADER1=(5/,18:'    Western Region',3/,
               18:'Profit and Loss Report',3/,
               18:'     for  ',&DATE,3/,
               18:'      Page',&PAGE),
   OUTREC=(6:16,13,24:31,10,ZD,M5,LENGTH=20,75:X),
   SECTIONS=(3,10,SKIP=P,
    HEADER3=(2:'Division:  ',3,10,5X,'Page:',&PAGE,2/,
             6:'Branch Office',24:'       Profit/(Loss)',/,
             6:'-------------',24:'--------------------'),
    TRAILER3=(6:'=============',24:'====================',/,
             6:'Total',24:TOTAL=(31,10,ZD,M5,LENGTH=20),/,
             6:'Lowest',24:MIN=(31,10,ZD,M5,LENGTH=20),/,
             6:'Highest',24:MAX=(31,10,ZD,M5,LENGTH=20),/,
             6:'Average',24:AVG=(31,10,ZD,M5,LENGTH=20),/,
             3/,2:'Average for all Branch Offices so far:',
                X,SUBAVG=(31,10,ZD,M5))),
    TRAILER1=(8:'Page ',&PAGE,5X,'Date:  ',&DATE,5/,
            8:'Total Number of Branch Offices Reporting:  ',
              COUNT,2/,
            8:'Summary of Profit/(Loss) for all',
              ' Western Division Branch Offices',2/,
            12:'Total:',
                22:TOTAL=(31,10,ZD,M5,LENGTH=20),/,
            12:'Lowest:',
                22:MIN=(31,10,ZD,M5,LENGTH=20),/,
            12:'Highest:',
                22:MAX=(31,10,ZD,M5,LENGTH=20),/,
            12:'Average:',
                22:AVG=(31,10,ZD,M5,LENGTH=20))
      give outfil1.dat
Parent topic: Sort Using OUTFIL for Complex Reporting
Related information
Input Data
Output


Output

                     Western Region

                 Profit and Loss Report

                      for  11/05/95

                       Page     1
************************************************************
  Division:  Chips          Page:     2

     Branch Office            Profit/(Loss)
     -------------     --------------------
     Gilroy                     554,843.42
     Los Angeles                (22,340.14)
     Morgan Hill                987,322.32
     Oakland                    234,124.32
     San Francisco              (32,434.31)
     San Jose                 1,232,133.35
     San Martin                 889,022.03
     =============     ====================
     Total                    3,842,670.99
     Lowest                     (32,434.31)
     Highest                  1,232,133.35
     Average                    548,952.99

 Average for all Branch Offices so far:     548,952.99
************************************************************
  Division:  Ice Cream      Page:     3

     Branch Office            Profit/(Loss)
     -------------     --------------------
     Marin                      542,341.23
     Napa                       857,342.83
     San Francisco              922,312.45
     San Jose                      (234.55)
     San Martin               1,003,467.30
     =============     ====================
     Total                    3,325,229.26
     Lowest                        (234.55)
     Highest                  1,003,467.30
     Average                    665,045.85

 Average for all Branch Offices so far:     597,325.02
************************************************************
  Division:  Pretzels       Page:     4

     Branch Office            Profit/(Loss)
     -------------     --------------------
     Marin                    5,343,323.44
     Morgan Hill                843,843.40
     Napa                     5,312,348.56
     San Francisco            5,412,300.05
     San Jose                 1,234,885.34
     San Martin                  (2,343.82)
     =============     ====================
     Total                   18,144,356.97
     Lowest                      (2,343.82)
     Highest                  5,412,300.05
     Average                  3,024,059.49

 Average for all Branch Offices so far:   1,406,236.51
************************************************************
        Page      5     Date:  11/05/95

       Total Number of Branch Offices Reporting:        18

       Summary of Profit/(Loss) for all Western Division
          Branch Offices

           Total:          25,312,257.22
           Lowest:            (32,434.31)
           Highest:         5,412,300.05
           Average:         1,406,236.51
Parent topic: Sort Using OUTFIL for Complex Reporting
Related information
Input Data
Mfsort Command


Workfile

During a sort or merge operation, mfsort uses a temporary workfile. This workfile is paged to disk in the current directory or, if it is set, in the directory specified by the TMPDIR environment variable. If not set, the current working directory is used.

Mfsort copies all the records from each of the input files to the temporary workfile, truncated or padded as appropriate. The workfile is then sorted or merged according to its key description. After being sorted or merged in the workfile, the records are copied to each of the output files and truncated or padded as appropriate.

During this operation:

  • If you do not need any of the records to be truncated, you must ensure that the record length of the workfile is sufficient for the longest record to be sorted
  • If your input files are of variable length and the sort workfile is not, all concept of variable-length is lost
  • If your input file is fixed length and the workfile is variable length, the record length of the record in the workfile is either the fixed length of the input file or the maximum record length of the workfile, whichever is the smaller


Error Messages

A full list of mfsort error messages is given in the topic Mfsort Error Messages.

Parent topic: MFSORT and MFJSORT Utilities
Related reference
Mfsort Error Messages
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands


Sorting Files

  • Callable Sort Module
  • SORT Environment Variables
  • Mfsort Error Messages
Parent topic: File Handling Reference


Callable Sort Module

  • Sort Module Function Codes
  • Sort File Control Description
Parent topic: Sorting Files


Sort Module Function Codes

x"FA01" | Initiates the sort operation. If the number of USING files is other than zero, the sort starts immediately, using the specified files as input. If the number of GIVING files is other than zero, the sort operation processes the GIVING files before returning control to the calling program.
x"FA40" | Initiates the merge operation. For this operation the number of USING files must be other than zero. It is assumed that the records in each of the USING files are already sorted.
x"FAF3" | Releases a record to the sort operation. You should use this function only when the number of USING files is zero.
x"FA10" | Terminates the input stage of the sort operation. You should use this function only when the number of USING files is zero. It indicates that no more release operations are to be performed. If the number of GIVING files is other than zero, the sort operation writes the sorted data to the GIVING file and terminates.
x"FAF5" | Returns a record from the sort or merge operation. You should use this function only when the number of GIVING files is zero.
x"FA88" | Terminates the sort or merge operation, releasing all memory allocated for the operation and deleting any temporary files. You should use this function only when the number of GIVING files is zero. It indicates that no more return operations are to be performed.
Parent topic: Callable Sort Module


Sort File Control Description

The FCD used by the Callable Sort Module has the following fields in addition to, or overriding, the FCD used by the File Handler:
Field name | Size | Description of the field
fcd-use-files | 1 | Number of USING files involved in the sort operation (this can be zero)
fcd-give-files | 1 | Number of GIVING files involved in the sort operation (this can be zero)
fcd-col-seq-address | 4 | Pointer to the collating sequence (null if none used)
fcd-fildef-address | 4 | Pointer to the file definition block that defines the USING and GIVING files.

The key definition block is used to describe the structure of the key to be used in the sort operation. There is a pointer to this block in fcd-key-def-address in the Sort FCD.

For sort operations, only one key is allowed, although this key can have many components. Each of these components can be either ascending or descending and can have one of many different numeric formats. The first two bytes of the component definition area are used as follows:
Byte 0
Size: 1
bit 7 (x"80") | indicates duplicates to be returned in order
bit 6 (x"40") | indicates DESCENDING key
bit 1 (x"02") | indicates that SIGN is in EBCDIC format
bit 0 (x"01") | indicates that the data is in EBCDIC format
Byte 1
Size: 1
bit 7 (x"80")
indicates that the field is NUMERIC. If bit 7 is set:
bit 6 (x"40")
indicates that the field is SIGNED NUMERIC
bit 5 (x"20")
indicates that the field is a non-display field. If bit 5 is set:
bits 0 and 1
0 | indicates that the field is BINARY
1 | indicates that the field is PACKED-DECIMAL
2 | indicates that the field is COMP-X format
3 | indicates that the field is COMP-5 format
If bit 5 is not set (DISPLAY field) but bit 6 is set (SIGNED):
bits 0 and 1
0 | indicates SIGN TRAILING INCLUDED
1 | indicates SIGN TRAILING SEPARATE
2 | indicates SIGN LEADING INCLUDED
3 | indicates SIGN LEADING SEPARATE
bit 2 (value x"04")
indicates floating point
If bit 7 is not set:
Bit 1
set if the collating sequence specified in the FCD is to be applied to this field.

The file definition block is a table of pointers to the FCDs for each of the USING and GIVING files involved in the sort operation. The fcd-fildef-address field in the Sort FCD is a pointer to this area. The length of the file definition block is four times the total of the contents of the fields at offsets 52 and 53.

Parent topic: Callable Sort Module


SORT Environment Variables

The following environment variables can be used for configuring SORT:

  • MFJSERET
    Determines the response to an unsuccessful sort, copy or merge operation.
  • MFJSSTRICTSORT
    Enables strict mainframe emulation behavior during a sort.
  • MFJSTATS
    Produces a report for the SORT operation.
  • MFJSWINDOW
    Determines the sliding or fixed century window.
  • SORTCOMPRESS
    Determines whether to compress each record in a SORT operation.
  • SORTSCHEME
    To increase performance of a SORT operation, configure SORT to retain more of the record information in memory.
  • SORTSPACE
    Determines the amount of memory allocated to internal workspace for SORT operations.
  • SORTTEMPSPACE
    Determines the amount of temporary memory allocated for SORT operations.
  • TEMPDIR/ TMP/ TEMP
    Determines where the run-time system of the directory stores paging files.
Parent topic: Sorting Files


MFJSERET

Determines the response to an unsuccessful sort, copy or merge operation.

If this environment variable is not set, an unsuccessful operation and its program will terminate with an unrecoverable error (return code 16).

Parameters

ABEND
The operation will abend and its program will continue instead of terminating with an unrecoverable error (return code 16)

The default is that the variable is not set.

Example

MFJSERET=ABEND
Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS
Related reference
MFJSWINDOW


MFJSSTRICTSORT

Enables strict mainframe emulation behavior during a sort.

Parameters

ON/OFF
Enables or disables the following mainframe behavior:
  • All JCL statements must contain a SYSOUT parameter, otherwise they will abend.
  • Modification of a ZD number with value 0 through INREC or OUTREC processing now keeps its sign value.
  • Records that are shorter than the output file's LRECL will be padded with low-values instead of spaces.

The default is OFF.

Example

MFJSSTRICTSORT=ON
Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS
Related reference
MFJSWINDOW


MFJSTATS

Produces a report for the SORT operation.

Parameters

ON
The report is displayed to SYSOUT. If a report file already exists for a previous SORT operation, the new report is appended to it.
OFF
A report is not produced.

The default value is OFF.

Example

MFJSTATS=ON
Parent topic: SORT Environment Variables
Related concepts
MFJSERET
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS
Related reference
MFJSWINDOW


MFJSWINDOW

Determines the sliding or fixed century window.

Use this environment variable for Y2K compatibility, when two-digit year values are used.

Parameters

To set a sliding century window, set a value between 0 and 100. For example, a value of 80 would set a century window of 1931-2030 in 2011, 1932-2031 in 2012, and so on.

To set a fixed century window, set a value between 1000 and 3000. For example, a value of 1973 would set a century window of 1973-2072.

The default is a sliding value of 80 when emulating DFSORT, and a default value of 0 when emulating SYNCSORT. A value of 0 equates to a century window, starting in the current year.

Example

MFJSWINDOW=25

Comments

You can use this environment variable instead of the Y2PAST sort option.

Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


SORTCOMPRESS

Determines whether to compress each record in a SORT operation.

When SORTCOMPRESS is set, run-length encoding of sort records results in much better performance when records contain multiple repeated characters.

Parameters

0
No compression.
Any number not equal to 0
Compression of records.

The default value is 0.

Example

SORTCOMPRESS=5
Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
Related reference
MFJSWINDOW


SORTSCHEME

To increase performance of a SORT operation, configure SORT to retain more of the record information in memory.

You should consider setting this environment variable if the total size of files in your SORT operation is over 1GB.

Parameters

0
During a SORT operation, temporary files are created to hold the non-key data portions of a record that are greater than 1024 bytes.
1

During a SORT operation, non-key data portions of a record are held in memory depending on the size of SORTSPACE:

Size of SORTSPACE | Maximum non-key data portion held in memory
1MB or greater | 5KB
4MB or greater | 12KB
8MB or greater | 28KB
16MB or greater | 62KB
Note: In general, the non-key data portion is the size of the record minus the size of the key data.

The default value is 0.

Example

SORTSCHEME=1
Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTCOMPRESS
Related reference
MFJSWINDOW


SORTSPACE

Determines the amount of memory allocated to internal workspace for SORT operations.

Typically, increasing SORTSPACE will improve the overall performance of SORT operations. This can be improved further by the use of SORTSCHEME when the files to be sorted are over 1GB.

Parameters

workspace size

Specify the amount of memory in one of the following formats:

Format | Workspace size
64M | 64 megabytes
2G | 2 gigabytes
1000000 | 1,000,000 bytes

The default value is 1,048,576 bytes (1MB).

The minimum value is 65,536 bytes (64KB).

The maximum value is 4,294,967,295 bytes (4GB - 1 byte).

Examples

SORTSPACE=64M
SORTSPACE=2G
SORTSPACE=1000000
Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSCHEME
SORTCOMPRESS
Related reference
MFJSWINDOW


SORTTEMPSPACE

Determines the amount of temporary memory allocated for SORT operations.

If you cannot set SORTSPACE to allocate enough contiguous memory for a SORT operation, set SORTTEMPSPACE to the required amount, and then reduce the amount allocated by SORTSPACE. The memory required for the SORT operation can then be allocated in smaller chunks.

We recommend that you use SORTTEMPSPACE only if you are receiving COBRT105 Memory allocation error (Fatal) errors.

Parameters

workspace size

Specify the amount of memory in one of the following formats:

Format | Workspace size
64M | 64 megabytes
2G | 2 gigabytes
1000000 | 1,000,000 bytes

The default value is 1,048,576 bytes (1MB).

The minimum value is 65,536 bytes (64KB).

The maximum value is 4,294,967,295 bytes (4GB - 1 byte).

Example

SORTTEMPSPACE=64M
Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
SORTSPACE
SORTSCHEME
SORTCOMPRESS
Related reference
MFJSWINDOW


TEMPDIR/ TMP/ TEMP

Determines where the run-time system of the directory stores paging files.

By default, the paging files are stored in the current directory.

Parameters

pathname
Specify the pathname for the paging files, using the correct environment variable for your operating system:
Platform | Environment variable
UNIX | TMPDIR
Windows or other | TMP (or TEMP if TMP is not set)

Example

TMPDIR=/home/temp	*> UNIX
TMP=C:\temp		 *> WINDOWS
Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
MFJSSTRICTSORT
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS
Related reference
MFJSWINDOW


Mfsort Error Messages

Select the range containing your message number:

  • Messages 0001 to 0099
  • Messages 0100 to 0199
  • Messages 0200 to 0399
Parent topic: Sorting Files


Messages 0001 to 0099

Select the number of the message you require details about:

  • SORT011U SYSIN dataset value missing
  • SORT012U SYSIN dataset value missing
  • SORT013U I/O error on dataset value
  • SORT014U Status = value
  • SORT015U Command statement error(s) detected
    The sort will not execute because of errors found during the parsing of the command.
  • SORT019I Key length truncated to 4096 bytes
  • SORT020U SORT(EXTSM) failed - sort engine status = Value
    An unexpected failure occured after the sort had been initiated. This message indicates the returned sort file status value.
  • SORT032I Number records sorted
  • SORT033I Number records merged
  • SORT034I Number records copied
  • SORT036U SORTIN record length missing or invalid
    You did not specify a record length in the RECORD instruction, or else you specified an invalid length.
  • SORT037U SYSIN RECFM value invalid
  • SORT038U SORTIN RECFM value invalid
    The record format in the RECORD instruction for the input file is invalid.
  • SORT039U SORTOUT RECFM value invalid
    The record format in the RECORD instruction for the output file is invalid.
  • SORT040U SORT terminated by E15 Operator
    The user exit routine E15 has terminated the sort process.
  • SORT041U SORT terminated by E35 Operator
    The user exit routine E35 has terminated the sort process.
  • SORT042U Memory allocation failure
    The mfsort utility was unable to allocate the required memory.
  • SORT043U Too many OUTFIL files specified
    You have specified too many files in the OUTFIL option.
  • SORT044U Too many USE files specified
    You have specified too many files in the USE instruction.
  • SORT045U Too many GIVE files specified
    You have specified too many files in the GIVE instruction.
  • SORT050U ICETOOL input file not found
    The file that is to be sorted has not been found.
  • SORT051U ICETOOL output file not found
    The definition for the output file has not been found.
  • SORT090U SORT terminated - missing SYSOUT
    No catalog entry has been found for the SYSOUT file.
  • SORT091U SORT terminated - missing SYSIN
  • SORT092U SORT terminated - missing SORTOUT
  • SORT093U SORT terminated - missing SORTIN or SORTIN01
  • SORT094U SORT terminated - missing SORTOFvalue
  • SORT095U SORT terminated - Bad data in CHANGE field
    Please see the CHANGE and DFSORT documentation on the Micro Focus Web site.
  • SORT096U SORT terminated - missing FNAMES dataset value
    Please see the FNAMES and DFSORT documentation on the Micro Focus Web site.
Parent topic: Mfsort Error Messages


SORT011U SYSIN dataset value missing

Parent topic: Messages 0001 to 0099


SORT012U SYSIN dataset value missing

Parent topic: Messages 0001 to 0099


SORT013U I/O error on dataset value

Parent topic: Messages 0001 to 0099


SORT014U Status = value

Parent topic: Messages 0001 to 0099


SORT015U Command statement error(s) detected

The sort will not execute because of errors found during the parsing of the command.
Parent topic: Messages 0001 to 0099


SORT019I Key length truncated to 4096 bytes

Parent topic: Messages 0001 to 0099


SORT020U SORT(EXTSM) failed - sort engine status = Value

An unexpected failure occured after the sort had been initiated. This message indicates the returned sort file status value.

Resolution:

Investigate the file status. See the topic File Status.

Parent topic: Messages 0001 to 0099


SORT032I Number records sorted

Parent topic: Messages 0001 to 0099


SORT033I Number records merged

Parent topic: Messages 0001 to 0099


SORT034I Number records copied

Parent topic: Messages 0001 to 0099


SORT036U SORTIN record length missing or invalid

You did not specify a record length in the RECORD instruction, or else you specified an invalid length.

Resolution:

Provide or correct the record length and resubmit the sort.

Parent topic: Messages 0001 to 0099


SORT037U SYSIN RECFM value invalid

Parent topic: Messages 0001 to 0099


SORT038U SORTIN RECFM value invalid

The record format in the RECORD instruction for the input file is invalid.

Resolution:

Correct the record format and resusbmit the sort.

Parent topic: Messages 0001 to 0099


SORT039U SORTOUT RECFM value invalid

The record format in the RECORD instruction for the output file is invalid.

Resolution:

Correct the record format and resusbmit the sort.

Parent topic: Messages 0001 to 0099


SORT040U SORT terminated by E15 Operator

The user exit routine E15 has terminated the sort process.
Parent topic: Messages 0001 to 0099


SORT041U SORT terminated by E35 Operator

The user exit routine E35 has terminated the sort process.
Parent topic: Messages 0001 to 0099


SORT042U Memory allocation failure

The mfsort utility was unable to allocate the required memory.

Resolution:

Try reducing the value of the SORTSPACE environment variable.

Parent topic: Messages 0001 to 0099


SORT043U Too many OUTFIL files specified

You have specified too many files in the OUTFIL option.

Resolution:

Respecify your mfsort command with an OUTFIL instruction that names up to 100 files.

Parent topic: Messages 0001 to 0099


SORT044U Too many USE files specified

You have specified too many files in the USE instruction.

Resolution:

Respecify your mfsort command with a USE instruction that names up to 100 files.

Parent topic: Messages 0001 to 0099


SORT045U Too many GIVE files specified

You have specified too many files in the GIVE instruction.

Resolution:

Respecify your mfsort command with a GIVE instruction that names up to 100 files.

Parent topic: Messages 0001 to 0099


SORT050U ICETOOL input file not found

The file that is to be sorted has not been found.
Parent topic: Messages 0001 to 0099


SORT051U ICETOOL output file not found

The definition for the output file has not been found.
Parent topic: Messages 0001 to 0099


SORT090U SORT terminated - missing SYSOUT

No catalog entry has been found for the SYSOUT file.
Parent topic: Messages 0001 to 0099


SORT091U SORT terminated - missing SYSIN

Parent topic: Messages 0001 to 0099


SORT092U SORT terminated - missing SORTOUT

Parent topic: Messages 0001 to 0099


SORT093U SORT terminated - missing SORTIN or SORTIN01

Parent topic: Messages 0001 to 0099


SORT094U SORT terminated - missing SORTOFvalue

Parent topic: Messages 0001 to 0099


SORT095U SORT terminated - Bad data in CHANGE field

Please see the CHANGE and DFSORT documentation on the Micro Focus Web site.
Parent topic: Messages 0001 to 0099


SORT096U SORT terminated - missing FNAMES dataset value

Please see the FNAMES and DFSORT documentation on the Micro Focus Web site.
Parent topic: Messages 0001 to 0099


Messages 0100 to 0199

Select the number of the message you require details about:

  • SORT100E Missing operator
    An operator was expected but was not found. An operator identifies the type of operation to be performed, SORT or MERGE.
  • SORT101E Malformed operator
  • SORT102E Expected operand missing
  • SORT103E Invalid operator operator
    You have specified an unexpected operator in a command file.
  • SORT104E Invalid operand keyword keyword
    You have specified unexpected syntax in the middle of an instruction.
  • SORT105E Expected continuation not present
    The sort instruction is not complete and is not continued on the next line.
  • SORT106E Field formats improperly specified
    You specified an invalid data type in the FIELDS instruction.
  • SORT107E Field format field-format invalid
    You specified invalid data in the FIELDS instruction.
  • SORT108E Sequence sequence invalid
    You specified an invalid sort order in FIELDS instruction..
  • SORT109E Too many fields specified
    You specified too many fields. The maximum is 100.
  • SORT110E Non-numeric data detected
    Non-numeric data was read where numeric data was expected.
  • SORT111E operator operator already processed
    You have already specified this instruction or parameter to an instruction.
  • SORT112E exit exit not supported
    You tried to use a user exit that is not supported.
  • SORT114E Expected '(' not found
    You specified an instruction that takes multiple parameters inside parentheses, but the opening parenthesis was not found.
  • SORT115E Boolean operator operator invalid
    The combination of format and bit operator is invalid.
  • SORT118E SORT / MERGE conflict
    You have specified both SORT and MERGE.
  • SORT119E INCLUDE / OMIT conflict
    You have specified both INCLUDE and OMIT.
  • SORT120E SORT statement missing FIELDS operand
    You have omitted the FIELDS instruction.
  • SORT121E MERGE statement missing FIELDS operand
    You have omitted the FIELDS instruction.
  • SORT122E INCLUDE statement missing COND operand
    You have omitted the COND parameter from the INCLUDE instruction.
  • SORT123E OMIT statement missing COND operand
    You have omitted the COND parameter from the INCLUDE instruction.
  • SORT124E FIELD position field-position invalid
    The starting position of the field is greater than the record length.
  • SORT125E FIELD length field-length invalid
    The field length is invalid in the FIELDS instruction.
  • SORT126E RECORD length record-length invalid
  • SORT127E Missing SORT/MERGE/COPY command statement
    You have not specified a SORT or a MERGE or a COPY instruction.
  • SORT128E Expected ')' not found
    You specified an instruction that takes multiple parameters inside parentheses, but the closing parenthesis was not found.
  • SORT129E Expected '=' not found
    You specified an instruction that takes multiple parameters specified using keyword=value pairs. No = sign was found.
  • SORT130E Expected 'F' OR 'V' not found
    The format parameter in the RECORDS instruction was not followed by F (for fixed) or V(for variable).
  • SORT131E Expected 'IX', 'RL', 'SQ', or 'LS' not found
    You have specified an ORG instruction for the USE or GIVE instruction but have not specified one of the above options.
  • SORT132E Prime key must be specified first
    The primary key was not specified first in the KEY instruction.
  • SORT133E Expected 'P', 'AD', 'A', or 'C' not found
    You have specified a KEY instruction for an indexed file in the GIVE instruction but have not specified one of the above options.
  • SORT134E Keyword/value value invalid for DFSORT emulation
    You have specififed a keyword=value pair that is invalid in mfsort's emulation of DFSORT.
  • SORT135E Keyword/value value invalid for SYNCSORT emulation
    You have specififed a keyword=value pair that is invalid in mfsort's emulation of SYNCSORT.
  • SORT136E No GIVE file specified for OUTFIL group
    You have not specified a GIVE file for the OUTFIL option.
  • SORT137E No USE file specified
    You have not specified a USE file.
  • SORT138E Target literal literal too long in CHANGE
    The target literal for the parameter CHANGE is too long.
  • SORT139E Substring comparison must be with character literal
    In the substring comparison of an INCLUD or OMIT condition, you have not specified a character literal for the right-hand side of the comparison.
  • SORT140E Invalid binary digit detected
  • SORT141E Cannot specify SAVE with either INCLUDE or OMIT
    In an OUTFIL group, you have specified SAVE with both INCLUDE and OMIT.
  • SORT142E Repeated FILE= or FNAMES=
  • SORT191I Operator operator ignored
    You have specified syntax that is not supported.
  • SORT192I Operand operand ignored
    You have specified syntax that is not supported.
  • SORT193E Invalid hex digit detected
  • SORT194 I No ALTSEQ command specified for 'AQ' SORT field formats; 'CH' assumed
  • SORT196E SUM / COPY conflict
    You have specified SUM together with the COPY option.
  • SORT197E INREC / MERGE conflict
  • SORT198E Non-numeric data detected in 'ZD' SUM field
  • SORT199E Too many OUTFIL statements
Parent topic: Mfsort Error Messages


SORT100E Missing operator

An operator was expected but was not found. An operator identifies the type of operation to be performed, SORT or MERGE.

Resolution:

Ensure that your SORT or MERGE instruction appears between columns 2 and 71 on the command line.

Parent topic: Messages 0100 to 0199


SORT101E Malformed operator

Parent topic: Messages 0100 to 0199


SORT102E Expected operand missing

Parent topic: Messages 0100 to 0199


SORT103E Invalid operator operator

You have specified an unexpected operator in a command file.

Resolution:

Resubmit the command file after removing the invalid operator.

Parent topic: Messages 0100 to 0199


SORT104E Invalid operand keyword keyword

You have specified unexpected syntax in the middle of an instruction.

Resolution:

Respecify the command removing the invalid keyword.

Parent topic: Messages 0100 to 0199


SORT105E Expected continuation not present

The sort instruction is not complete and is not continued on the next line.

Resolution:

Provide a complete instruction, using a continuation line if necessary.

Parent topic: Messages 0100 to 0199


SORT106E Field formats improperly specified

You specified an invalid data type in the FIELDS instruction.
Parent topic: Messages 0100 to 0199


SORT107E Field format field-format invalid

You specified invalid data in the FIELDS instruction.
Parent topic: Messages 0100 to 0199


SORT108E Sequence sequence invalid

You specified an invalid sort order in FIELDS instruction..

Resolution:

Resubmit the sort specifying either A (ascending) or D (descending).

Parent topic: Messages 0100 to 0199


SORT109E Too many fields specified

You specified too many fields. The maximum is 100.
Parent topic: Messages 0100 to 0199


SORT110E Non-numeric data detected

Non-numeric data was read where numeric data was expected.
Parent topic: Messages 0100 to 0199


SORT111E operator operator already processed

You have already specified this instruction or parameter to an instruction.

Resolution:

Remove the duplication and resubmit.

Parent topic: Messages 0100 to 0199


SORT112E exit exit not supported

You tried to use a user exit that is not supported.

Resolution:

Only user exits E15 and E35 are supported.

Parent topic: Messages 0100 to 0199


SORT114E Expected '(' not found

You specified an instruction that takes multiple parameters inside parentheses, but the opening parenthesis was not found.
Parent topic: Messages 0100 to 0199


SORT115E Boolean operator operator invalid

The combination of format and bit operator is invalid.
Parent topic: Messages 0100 to 0199


SORT118E SORT / MERGE conflict

You have specified both SORT and MERGE.

Resolution:

Respecify the command using either SORT or MERGE.

Parent topic: Messages 0100 to 0199


SORT119E INCLUDE / OMIT conflict

You have specified both INCLUDE and OMIT.

Resolution:

Respecify the command using either INCLUDE or OMIT.

Parent topic: Messages 0100 to 0199


SORT120E SORT statement missing FIELDS operand

You have omitted the FIELDS instruction.
Parent topic: Messages 0100 to 0199


SORT121E MERGE statement missing FIELDS operand

You have omitted the FIELDS instruction.
Parent topic: Messages 0100 to 0199


SORT122E INCLUDE statement missing COND operand

You have omitted the COND parameter from the INCLUDE instruction.
Parent topic: Messages 0100 to 0199


SORT123E OMIT statement missing COND operand

You have omitted the COND parameter from the INCLUDE instruction.
Parent topic: Messages 0100 to 0199


SORT124E FIELD position field-position invalid

The starting position of the field is greater than the record length.
Parent topic: Messages 0100 to 0199


SORT125E FIELD length field-length invalid

The field length is invalid in the FIELDS instruction.
Parent topic: Messages 0100 to 0199


SORT126E RECORD length record-length invalid

Parent topic: Messages 0100 to 0199


SORT127E Missing SORT/MERGE/COPY command statement

You have not specified a SORT or a MERGE or a COPY instruction.

Resolution:

Respecify the mfsort command using one of these instructions.

Parent topic: Messages 0100 to 0199


SORT128E Expected ')' not found

You specified an instruction that takes multiple parameters inside parentheses, but the closing parenthesis was not found.
Parent topic: Messages 0100 to 0199


SORT129E Expected '=' not found

You specified an instruction that takes multiple parameters specified using keyword=value pairs. No = sign was found.
Parent topic: Messages 0100 to 0199


SORT130E Expected 'F' OR 'V' not found

The format parameter in the RECORDS instruction was not followed by F (for fixed) or V(for variable).
Parent topic: Messages 0100 to 0199


SORT131E Expected 'IX', 'RL', 'SQ', or 'LS' not found

You have specified an ORG instruction for the USE or GIVE instruction but have not specified one of the above options.

Resolution:

Respecify the ORG instruction for the USE or GIVE instruction using one of the options IX, RL, SQ, or LS.

Parent topic: Messages 0100 to 0199


SORT132E Prime key must be specified first

The primary key was not specified first in the KEY instruction.

Resolution:

Reorganise the key definition so that you specify the primary key first.

Parent topic: Messages 0100 to 0199


SORT133E Expected 'P', 'AD', 'A', or 'C' not found

You have specified a KEY instruction for an indexed file in the GIVE instruction but have not specified one of the above options.

Resolution:

Respecify the KEY for the GIVE instruction using one of P, AD, A, or C.

Parent topic: Messages 0100 to 0199


SORT134E Keyword/value value invalid for DFSORT emulation

You have specififed a keyword=value pair that is invalid in mfsort's emulation of DFSORT.
Parent topic: Messages 0100 to 0199


SORT135E Keyword/value value invalid for SYNCSORT emulation

You have specififed a keyword=value pair that is invalid in mfsort's emulation of SYNCSORT.
Parent topic: Messages 0100 to 0199


SORT136E No GIVE file specified for OUTFIL group

You have not specified a GIVE file for the OUTFIL option.

Resolution:

Specify the GIVE file.

Parent topic: Messages 0100 to 0199


SORT137E No USE file specified

You have not specified a USE file.

Resolution:

Specify one or more USE files.

Parent topic: Messages 0100 to 0199


SORT138E Target literal literal too long in CHANGE

The target literal for the parameter CHANGE is too long.
Parent topic: Messages 0100 to 0199


SORT139E Substring comparison must be with character literal

In the substring comparison of an INCLUD or OMIT condition, you have not specified a character literal for the right-hand side of the comparison.

Resolution:

Respecify the substring comparison, replacing its right-hand side with a character literal.

Parent topic: Messages 0100 to 0199


SORT140E Invalid binary digit detected

Parent topic: Messages 0100 to 0199


SORT141E Cannot specify SAVE with either INCLUDE or OMIT

In an OUTFIL group, you have specified SAVE with both INCLUDE and OMIT.

Resolution:

Respecify the SAVE instruction with either INCLUDE or OMIT.

Parent topic: Messages 0100 to 0199


SORT142E Repeated FILE= or FNAMES=

Parent topic: Messages 0100 to 0199


SORT191I Operator operator ignored

You have specified syntax that is not supported.
Parent topic: Messages 0100 to 0199


SORT192I Operand operand ignored

You have specified syntax that is not supported.
Parent topic: Messages 0100 to 0199


SORT193E Invalid hex digit detected

Parent topic: Messages 0100 to 0199


SORT194 I No ALTSEQ command specified for 'AQ' SORT field formats; 'CH' assumed

Parent topic: Messages 0100 to 0199


SORT196E SUM / COPY conflict

You have specified SUM together with the COPY option.

Resolution:

Respecify your mfsort command with either SUM or COPY.

Parent topic: Messages 0100 to 0199


SORT197E INREC / MERGE conflict

Parent topic: Messages 0100 to 0199


SORT198E Non-numeric data detected in 'ZD' SUM field

Parent topic: Messages 0100 to 0199


SORT199E Too many OUTFIL statements

Parent topic: Messages 0100 to 0199


Messages 0200 to 0399

Select the number of the message you require details about:

  • SORT200E Bad or unknown symbol
  • SORT201E No previous offset defined for symbols
  • SORT202E No previous length defined for symbols
  • SORT203E No previous format defined for symbols
  • SORT204I *********************Sort Statistics*********************
  • SORT205I INPUT file filename
  • SORT206I OUTPUT file filename
  • SORT207I OUTFIL file filename
  • SORT214I Format operand ignored
  • SORT215E Reformatting field error
  • SORT216I Record type is V - Data starts at position 5
    You specified variable organisation for a file and also a start position in the FIELDS instruction before position 5.
  • SORT217I Record length L1 or L3 overridden
  • SORT232E Field length exceeds maximum allowed
  • SORT399I End of Micro Focus MFJSORT Utility
Parent topic: Mfsort Error Messages


SORT200E Bad or unknown symbol

Parent topic: Messages 0200 to 0399


SORT201E No previous offset defined for symbols

Parent topic: Messages 0200 to 0399


SORT202E No previous length defined for symbols

Parent topic: Messages 0200 to 0399


SORT203E No previous format defined for symbols

Parent topic: Messages 0200 to 0399


SORT204I *********************Sort Statistics*********************

Parent topic: Messages 0200 to 0399


SORT205I INPUT file filename

Parent topic: Messages 0200 to 0399


SORT206I OUTPUT file filename

Parent topic: Messages 0200 to 0399


SORT207I OUTFIL file filename

Parent topic: Messages 0200 to 0399


SORT214I Format operand ignored

Parent topic: Messages 0200 to 0399


SORT215E Reformatting field error

Parent topic: Messages 0200 to 0399


SORT216I Record type is V - Data starts at position 5

You specified variable organisation for a file and also a start position in the FIELDS instruction before position 5.

This message is followed by message SORT217I Record length L1 or L3 overridden.

Parent topic: Messages 0200 to 0399


SORT217I Record length L1 or L3 overridden

Parent topic: Messages 0200 to 0399


SORT232E Field length exceeds maximum allowed

A sum field is longer than 18 digits. This is the maximum size of any numeric string used in MFJSORT.

Parent topic: Messages 0200 to 0399


SORT399I End of Micro Focus MFJSORT Utility

Parent topic: Messages 0200 to 0399


Tracing File Operations

  • Introduction
  • Configuring Tracing and Logging
  • Dynamic Tracing
Parent topic: File Handling Reference


Introduction

The File Handler includes tracing file operations that enable you to:

  • Set tracing on or off using file handler configuration parameters
  • Set a further level of tracing known as logging, again using file handler configuration parameters
  • Dynamically turn tracing on or off from your COBOL program, using library routines
Parent topic: Tracing File Operations
Related information
Configuring Tracing and Logging
Dynamic Tracing


Configuring Tracing and Logging

You use the File Handler configuration parameters TRACE, TRACEFILEEXTEND, TRACEFILENAME, LOG and LOGFILENAME to control tracing and logging activities:

  • Set TRACE=ON to turn tracing on
  • Set TRACEFILEEXTEND=ON to indicate that you want trace information to be written to the end of the current trace file, if the trace file already exists
  • Set TRACEFILENAME=filename if you want the trace file to have a name other than the default, which is xfhtrace.xfh
  • Set LOG=ON to indicate that you want any unusual file-related situations, such as corrupted files, or automatic file recovery, to be recorded in a log file for later examination
  • Set LOGFILENAME=filename if you want the log file to have a name other than the default, which is xfhlog

You can set TRACE and LOG either globally or for individual files, but you can only set TRACEFILEEXTEND, TRACEFILENAME and LOGFILENAME globally.

Here is an example configuration file:

[XFH-DEFAULT]
TRACE=OFF
TRACEFILENAME=/trace/mftracefile.xfh
TRACEFILEEXTEND=ON
LOG=ON
LOGFILENAME=/temp/mflogfile.log

[datafile1.dat]
TRACE=ON

[datafile2.dat]
LOG=OFF

In this example file tracing is set off globally and set on for the data file named datafile1.dat; new trace records are appended to the trace file, c:\trace\mftracefile.xfh, if it already exists. Logging is set on globally and set off for the data file named datafile2.dat.

Note: If the trace file might exceed a size of 4GB, ensure you specify the configuration options FILEMAXSIZE=8 and IDXFORMAT=8 (these are the default values).
Parent topic: Tracing File Operations
Related information
Introduction
Dynamic Tracing


Dynamic Tracing

You can turn tracing on and off from within a COBOL program either by setting the appropriate flags in the FCD or by using library routines. You might want to do this to focus on file handling problems in a subset of an application's operations. When you set FCD flags you do it for a particular file. When you use the library routines, the trace settings affect all the file operations executed by the program from that point on.

When you do dynamic tracing, you use two flags together. This is because file operations such as READs and WRITEs can be traced only if the OPEN operation was traced. If you execute a program with tracing turned off, open a file, then switch dynamic tracing on, the tracing mechanism won't be able to trace any subsequent operations. The best way to proceed is to switch dynamic tracing on for OPENs and CLOSEs at the beginning of the program, then switch tracing for all operations on and off as required. However, the tracing of OPEN and CLOSE operations on its own can also be useful.

  • Using the FCD to Control Tracing
  • Using Library Routines to Control Tracing
Parent topic: Tracing File Operations
Related information
Introduction
Configuring Tracing and Logging


Using the FCD to Control Tracing

To use the FCD flags you must have access to the FCD; see the topic Accessing the FCD in the section File Handler and Sort APIs.

File tracing is controlled by two flag bit settings within the FCD:

  • Bit 1 of fcd-flags-1 controls whether all file operations are traced.
  • Bit 3 of fcd-fs-flags controls whether OPEN and CLOSE operations only are traced.

Change these bit settings as required to control tracing for individual files.

Parent topic: Dynamic Tracing
Related information
Using Library Routines to Control Tracing


Using Library Routines to Control Tracing

If you want to use dynamic tracing in a program you must first issue a call to the mFFH library routine or perform an I/O operation using a standard COBOL statement. This initializes the File Handler.

The library routines provide a means of obtaining the same tracing behavior as setting the FCD flags without the need to have the FCD available. All changes to tracing behavior made using the library routines affect all files subsequently accessed.

To control tracing, issue calls to the MFFH_MODIFY_TRACE library routine. You can:

  • Set the main tracing flag on and off
  • Set the OPEN/CLOSE tracing flag on and off
  • Disable a modification that you set earlier

To disable all the modifications that you have set, issue a call to the library routine MFFH_MODIFY_DISABLE.

For further information see the topics mFFH, MFFH_MODIFY_TRACE and MFFH_MODIFY_DISABLE.

Parent topic: Dynamic Tracing
Related information
Using the FCD to Control Tracing


Fileshare Guide

Fileshare is a client/server system designed to provide more efficient processing of data files that are accessed concurrently, across a network, by a large number of users.

In addition, Fileshare offers features that are not available with the base COBOL file handler including transaction processing and rollforward recovery logging.

  • Introduction
    This chapter gives a brief overview of the facilities provided by Fileshare and also describes how Fileshare works.
  • Standard Operation
    This chapter describes what you need to do at the Fileshare Client and Fileshare Server machines to enable a standard COBOL program to use Fileshare. Once you have read this chapter, you should be able to configure any COBOL program to use Fileshare.
  • Configuring CCI Communications for Fileshare
  • Database Integrity
    This chapter describes all of those Fileshare features which enable you to safeguard the integrity of your database:
  • Security
    Fileshare provides security features which enable you to restrict access to a Fileshare Server.
  • Advanced Operation
    This chapter describes the advanced features that are available with Fileshare.
  • Fileshare on UNIX
    This chapter describes Fileshare on UNIX.
  • Error Handling
    Fileshare error messages are listed in the chapter Fileshare Server Messages .
  • Fileshare Server Messages
    There are three levels of messages that can be produced by the Fileshare Server.
Parent topic: Micro Focus COBOL Server for UNIX


Introduction

  • Overview
  • How Fileshare Works
Parent topic: Fileshare Guide
Related information
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Overview

Fileshare is best suited to applications that share data files, concurrently, between many users, across a network. It supports all of the functionality provided by the base COBOL file handling system and provides several additional features:

  • Reduced network traffic
  • Transaction processing
  • Rollforward recovery logging
  • Logon and file open security checks

The ability of any one application to take advantage of these features depends on:

  • The way the application processes the shared data files
  • The type of data files the application shares
  • The operating system on which the Fileshare Server is running
  • The communications protocol being used between the Fileshare Client and the Fileshare Server

You do not need to make any program source code changes to use the basic Fileshare system. Source code changes are only needed to take advantage of some of the advanced features provided by Fileshare.

Parent topic: Introduction
Related information
How Fileshare Works


How Fileshare Works

Using the base COBOL file handling system, a typical COBOL I/O request to a shared data file causes the file handler to make several accesses to that data file across the network. See Figure 1.

Figure 1. Conventional Network
Conventional Network

With Fileshare, a program that needs to access a data file has its request processed by the File Handling Redirector (FHRedir) module. The FHRedir module sends the request over the network to a Fileshare Server that performs the low-level I/O operations and then passes the result of the I/O operation, including the file status, back to FHRedir. FHRedir returns the result to the program. See Figure 2.

Figure 2. Fileshare Network
Fileshare Network

A Fileshare System is made up of:

Fileshare Clients | A Fileshare Client comprises a user program, making data file I/O requests, via the FHRedir module. FHRedir redirects the I/O requests to a Fileshare Server.
Fileshare Servers | A Fileshare Server runs on the same machine as the data files that you want to access. The Fileshare Server accepts requests across the network from the Fileshare Client, processes them by calling a local copy of the Micro Focus File Handler and then returns the result to the Fileshare Client.
Note:
  • The Fileshare Server and the Fileshare Client can be running on the same physical machine. For example, with a multi-tasking operating system such as Windows, the Fileshare Client can run in one session and the Fileshare Server can run in another session. Using this method, you can develop Fileshare applications on a single PC without actually sending data across a network. You should be aware, however, that performance improvements will not be observed, as no network is being used.
  • You can also run the Fileshare Server in the same session as the Fileshare Client using the single user mode of operation. This enables you to take advantage of advanced Fileshare features, such as transaction processing, without the need for a network or multiple sessions. For more information on the single user mode of operation, see the section Single User Mode in the chapter Advanced Operations.

Since a single Fileshare Server processes all the requests from several Fileshare Clients, it can use a single copy of the Micro Focus File Handler, regardless of how many users are accessing the Fileshare Server. This has several advantages:

  • The Fileshare Server can open the data files exclusively making full use of both its own cache and the operating system's cache
  • The Fileshare Server does not need to obtain semaphores on the data file. Normally semaphores are needed to control concurrent access to shared data files.
  • The Fileshare Server can process record locks internally without the need to make calls to the operating system
Parent topic: Introduction
Related information
Overview
Single User Mode


Standard Operation

  • Fileshare Client
  • Fileshare Server
Parent topic: Fileshare Guide
Related information
Introduction
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Fileshare Client

To enable your COBOL program to use Fileshare at the Fileshare Client machine, you need to do two things:

  • Force your program to pass file I/O requests to the File Handling Redirector module (FHR), thus creating a Fileshare Client
  • Configure your Fileshare Client, specifying the name of the Fileshare Server to connect to, and the communications protocol to use when connecting.

You might also need to configure CCI for the communications protocol you have chosen. For more details, please refer to:

  • Your online book Configuring CCI
  • Specifying the Fileshare Server
  • Specifying the Communications Protocol
  • Configuring Your Fileshare Client
  • Using the File Handling Redirector Module
  • FHREDIR Return Codes
Parent topic: Standard Operation
Related information
Fileshare Server


Specifying the Fileshare Server

Each Fileshare Server on the network is identified by a unique name, assigned when the Fileshare Server is started. The Fileshare Client uses this name to specify which Fileshare Server to use.

There are two ways to specify the Fileshare Server name:

  • As part of the filename in your program.

    This requires changes to your code.

  • In a Fileshare Client configuration file.

    This does not require changes to your code.

These methods are listed in the next two topics.

  • As a Filename
  • In a Configuration File
Parent topic: Fileshare Client
Related information
Specifying the Communications Protocol
Configuring Your Fileshare Client
Using the File Handling Redirector Module
FHREDIR Return Codes


As a Filename

Specifying the server as a filename in your program overrides any configuration file settings.

Windows:

select account-file assign to	"$$server1\c:\accounts\main.dat"

This SELECT statement tells the File Handling Redirector module to direct requests for this data file to the Fileshare Server named server1. The data file is main.dat in the directory accounts on drive c: on the Fileshare Server machine. The File Handling Redirector module passes the characters appearing after the text string $$server1\ to the Fileshare Server as the name of the file.

UNIX:

select account-file assign to	"$$server1//accounts/main.dat"

This SELECT statement tells the File Handling Redirector module to direct requests for this data file to the Fileshare Server named server1. The data file is main.dat in the directory accounts on the Fileshare Server machine. The File Handling Redirector module passes the characters appearing after the text string $$server1/ to the Fileshare Server as the name of the file.

Parent topic: Specifying the Fileshare Server
Related information
In a Configuration File


In a Configuration File

To specify a default Fileshare Server, use the /s option in the Fileshare Client configuration file. For example:

Windows:

/s server2

UNIX:

-s server2

tells the Fileshare Client to use the default Fileshare Server named server2. The File Handling Redirector module redirects all file I/O to this server unless you:

  • Specifically define a file as a local file. See the section Client Configuration in the chapter Configuration for further information.
  • Specify that a file is on a different Fileshare Server, using the Fileshare Client configuration file. See the section Client Configuration in the chapter Configuration for further information
  • Specify a different Fileshare Server as part of the filename in your program (see above)
Note:

  • The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names
  • Filenames appearing in the configuration file are case-sensitive unless defined by the /r option (DYNCONFIG), in which case they are not case sensitive when run in Windows
  • The filename in the configuration file must appear exactly as it will appear to the File Handling Redirector module on the first OPEN request passed by your program
Parent topic: Specifying the Fileshare Server
Related information
As a Filename
Client Configuration


Specifying the Communications Protocol

Fileshare over CCI supports several communications protocols. The protocol you use depends on the operating system the Fileshare Client and Fileshare Server(s) are running on and the type of network you are using. You specify the Fileshare CCI communications protocols in the client's cci.ini file.

The default protocol is TCP/IP (CCITCP).

If you require a communications protocol other than the default, you must specify it in the Fileshare Client configuration file.

To specify an alternative default CCI protocol, use the -cm option. For example:

  • To make the UNIX Named Pipes protocol (CCINAMPU) the default:
    -cm ccinampu
  • To specify that a particular CCI protocol is used when communicating with a specific Fileshare Server, use the -cm and -s options together:
    -cm ccinampu -s server1
    This tells the Fileshare Client to use the CCINAMPU for communicating with the Fileshare Server named server1.
  • To make the Fileshare Client use the TCP/IP protocol (CCITCP) as the default and CCINAMPU for communicating with server1:
    -cm ccitcp
-cm ccinampu -s server1
Note: The cci.ini file that ships with Enterprise Sever contains detailed comments that explain the various cci.ini options that you can use to alter the basic CCISMEM configuration. Most of these are rarely required.
Parent topic: Fileshare Client
Parent topic: Configuring CCI Communications for Fileshare
Related information
Specifying the Fileshare Server
Configuring Your Fileshare Client
Using the File Handling Redirector Module
FHREDIR Return Codes
About Fileshare Communications
Using CCITCP
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Configuring Your Fileshare Client

The Fileshare Client configuration file is an ordinary text file that you can create using any text editor. By default, it is called fhredir.cfg. The Fileshare Client searches for this file in the current working directory of your application and then along the path specified by the COBDIR environment variable, if one has been set up. Alternatively, you can specify the location of the Fileshare Client configuration file using the FHREDIR environment variable, for example:

Windows:

set FHREDIR=c:\client.cfg

This example tells the Fileshare Client to use the configuration file client.cfg in the root directory on drive c:.

UNIX:

set FHREDIR=/client.cfg
export FHREDIR

This example tells the Fileshare Client to use the configuration file client.cfg in the root directory.

Configuring the Fileshare Client enables you to specify how you want to treat your data files, that is, as either:

  • Local data files, located on the machine where the Fileshare Client is running. To access local data files, the Fileshare Client uses a local copy of the Micro Focus file handler. This is the default.
  • Remote data files, located on the machine where the Fileshare Server is running. To access remote files, I/O operations are redirected to the appropriate Fileshare Server by the File Handling Redirector module.

In order to redirect I/O operations successfully, the File Handling Redirector module needs to know:

  • Which Fileshare Server to communicate with
  • Which communications protocol to use when contacting the server
  • Fileshare Client Configuration Options
  • Example Client Configuration File
Parent topic: Fileshare Client
Related information
Specifying the Fileshare Server
Specifying the Communications Protocol
Using the File Handling Redirector Module
FHREDIR Return Codes


Fileshare Client Configuration Options

This section describes all of the available Fileshare Client configuration options. These options can appear as many times as necessary within a Fileshare Client configuration file, and in any order, but only one option can be specified per line.

Note:
  • The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names
  • Filenames appearing in the configuration file are case-sensitive unless defined by the /r option (DYNCONFIG), in which case they are not case sensitive when run in Windows
  • The filename in the configuration file must appear exactly as it will appear to FHRedir on the first OPEN request passed by your program
  • The Fileshare Server name is folded to uppercase. Note that it may be necessary to use the name in uppercase in some configuration files to ensure name matching works as expected.
  • UNIX:
    • In this section, options are shown starting with a forward slash (/). This is how you specify the options on Windows. On UNIX, use the hyphen (-) character instead of the forward slash.
    • Filenames are shown using the Windows file-naming convention. On UNIX, use the UNIX filenaming conventions.
Client Configuration Option Specifying
/bl
 Open a file exclusively to enable blocking, to improve performance.
/cm CCI-Protocol
 The default communications protocol for this Fileshare Client. Valid values for CCI-Protocol are listed in the table below.
/cm CCI-Protocol
/s ServerName
 The communications protocol to use when contacting the Fileshare Server, ServerName. Valid values for CCI-Protocol are listed in the table below.
/ct CCI-Timeout server-name
 The communications timeout period, specified in 1/10th seconds. The default is 1200 (120 seconds). See the section CCI Timeout in the chapter Communications for more information.
/cr CCI-Timeout
 The connection retry timeout period, specified in 1/10th seconds. The default is 0. This timeout is only for the initial connection and only applies if the CCI module returns and is out of memory or resources. The client will reattempt to connect at varying intervals up to the timeout period. However, the default is that the connection is only tried once.
/f Filename
/r Custom-File-Handler
 The data file Filename is a local file and should be actioned by the custom file handler. Repeat this option for eveyr data file you want assigned to a specific custome file handler that is not the default File Handler. Valid values for Filename and Custom-File-Handler are listed in the table below.

This option only applies if the environment variable DYNREDIR is set to DYNCONFIG.

/f Filename
/s ServerName
 The data file Filename is a remote file on the Fileshare Server named server-name. Repeat this option for every data file you want assigned to a specific Fileshare Server that is not the default Fileshare Server. Valid values for Filename and ServerName are listed in the table below.
/f Filename
 Filename is a local data file held on the PC where the Fileshare Client resides. Valid values for Filename are listed in the table below.
/s ServerName
 The ServerName as a default Fileshare Server

Accesses to data files not directed to a particular Fileshare Server or not defined as local data files are directed to the default Fileshare Servers. The order in which the default Fileshare Servers are defined in the Fileshare Client configuration file is the order in which the Fileshare Client contacts each Fileshare Server in an attempt to locate the file.

If the data file is not found on any Fileshare Server, the request for that data file is directed to the first default Fileshare Server listed in the configuration file.

Valid values for options in the Fileshare Client configuration file are:

Option | Valid Values
CCI-Protocol

Windows:

  • TCP IP: /ccitcp
  • CCISMEM: /ccism

UNIX:

  • TCP IP: -ccitcp: ccitcp
  • UNIX named pipes: -ccinampu
ServerName | Any character string up to 16 characters long depending on the CCI protocol you are using. The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names.
Filename Any valid filename that is supported by the operating system. Filenames cannot contain embedded space characters. You can use terminating wildcard characters in Filename to designate groups of files. For example, use
/f \accounts\*

to specify all files starting with the string "\accounts\".

Parent topic: Configuring Your Fileshare Client
Related information
Example Client Configuration File


Example Client Configuration File

This example shows a typical Fileshare Client configuration file.

/s server1
/s server2
/cm cciipx
/f \orders\* /s server3
/cm ccitcp /s server3
/f \accounts\payroll.dat
/f \transport\delivery\*
/f \returns\* /r module1!userfh1

where:

Line 1:
/s server1

Specifies that server1 is one of the default Fileshare Servers.

This Fileshare Server is searched for any file that is not defined as being on a particular Fileshare Server (see Line 4) or as local (see Lines 6 and 7). If you specify more than one default Fileshare Server (see Line 2), the Fileshare Servers are searched in the order that you have defined them in the configuration file. In this example, server1 is searched before server2.
Line 2:
/s server2

Specifies that server2 is also a default Fileshare Server. If you access a file that you have not defined to be on a particular Fileshare Server (see Line 4) or as local (see Lines 6 and 7), this Fileshare Server is searched after the Fileshare Server server1.

Line 3:
/cm cciipx

Specifies that the default communications protocol is CCIIPX. When the Fileshare Client tries to contact a Fileshare Server that does not have a specific CCI protocol defined (see Lines 1 and 2), this is the one used.

Line 4:
/f \orders\* /s server3

Specifies that FHRedir should direct all accesses to files with a name beginning with the string \orders\ to the Fileshare Server named server3.

Line 5:
/cm ccitcp /s server3

Specifies that the communications protocol to use when communicating with the Fileshare Server, server3 is ccitcp. This overrides any default CCI protocol specified in the Fileshare Client configuration file (see Line 3).

Line 6:
/f \accounts\payroll.dat

Specifies that the file \accounts\payroll.dat is a local file on the Fileshare Client machine. The Fileshare Client accesses this file using a local copy of the Callable File Handler.

Line 7:
/f \transport\delivery\*

Specifies that any files with a filename beginning with the string \transport\delivery\ are local files.
Line 8:
/f \returns\* /r module1!userfh1

Specifies that the customer file handler userfh1 in module1 should be used for all accesses to files with a name beginning with the string "\returns\".

Note that module1 specifies the library containing a custom file handler and that usedrfh1 is the name of the custom file's entry point.

This option only applies if the environment variable DYNREDIR is set to DYNCONFIG.
Parent topic: Configuring Your Fileshare Client
Related information
Fileshare Client Configuration Options


Using the File Handling Redirector Module

There are three ways of forcing your program to pass file I/O requests to the File Handling Redirector module:

  • If your program uses COBOL I/O syntax, you must compile it with the CALLFH"FHREDIR" Compiler directive so that the File Handling Redirector module processes any I/O requests that your program makes.
  • If your program uses the Micro Focus file handler API, you need to change the program so that it calls "FHREDIR" and not "EXTFH". (The call interface to the File Handling Redirector module is exactly the same as the call interface to the Callable File Handler (ExtFH).)

    For example:

    call "FHREDIR" using operation-code, fcd
  • Set the File Handler configuration option FHREDIR=ON.
    Note:

    Take care with this option. If it is in effect when Fileshare itself is running, Fileshare will attempt to redirect file I/O requests to itself, and this will cause a timeout failure.

When you have performed any of these actions, you have created a Fileshare Client but your program works in exactly the same way as it did before because the File Handling Redirector module simply forwards I/O requests to a local copy of the Micro Focus File Handler.

Parent topic: Fileshare Client
Related information
Specifying the Fileshare Server
Specifying the Communications Protocol
Configuring Your Fileshare Client
FHREDIR Return Codes


FHREDIR Return Codes

Each call to FHREDIR returns a status code in fcd-file-status in the FCD. Most codes returned are the usual file handling codes. The following codes specific to Fileshare might also be returned:

Code | Meaning
-128 | Fileshare Security is enabled and the user name specified by the caller is not found in the password file on the server.
-127 | The named file is not currently open by the fileshare server. This does not mean that the file does not exist on the disk.
-126 | Fileshare Security is enabled and the password given is incorrect.
-125 | The requested data is larger than the buffer provided to contain it. Increase the size of your buffer.
Parent topic: Fileshare Client
Related information
Specifying the Fileshare Server
Specifying the Communications Protocol
Configuring Your Fileshare Client
Using the File Handling Redirector Module


Fileshare Server

Before a Fileshare Server is invoked, you need to configure the Fileshare Server to specify:

  • The Fileshare Server name to use on the network
  • The communications protocols that it can use
  • Configuring the Fileshare Server
  • Starting the Fileshare Server
  • Stopping the Fileshare Server
Parent topic: Standard Operation
Related information
Fileshare Client


Configuring the Fileshare Server

You can specify these Fileshare Server configuration options in one of two ways:

  • On the command line (separated by spaces)
  • In a Fileshare Server configuration file (a text file which you can create using any text editor).

    The Fileshare Server identifies the configuration file to use by checking the FS environment variable:

    • If set, the Fileshare Server uses the configuration file specified by this variable
    • If not set, the Fileshare Server uses the default configuration file fs.cfg either in the current working directory of the Fileshare Server or on the path specified by the COBDIR environment variable
  • Specifying a Fileshare Server Name
  • Specifying the Communications Protocol
  • Fileshare Server Configuration Options
Parent topic: Fileshare Server
Related information
Starting the Fileshare Server
Stopping the Fileshare Server


Specifying a Fileshare Server Name

Each Fileshare Server is identified on the network by a unique name. This name is specified using the /s option, for example, the command line:

Windows:

fs /s server1

UNIX:

fs -s server1

registers the name of the Fileshare Server as server1.

Note:

The Fileshare Server cannot be initialized unless it registers a name on the network. The server-name can be up to 16 characters in length, depending on the CCI protocol you are using.

Parent topic: Configuring the Fileshare Server
Related information
Specifying the Communications Protocol
Fileshare Server Configuration Options


Specifying the Communications Protocol

By default the Fileshare Server uses CCITCP to communicate with Fileshare Clients using the TCP/IP protocol. You need to specify any other protocol you want Fileshare to use by specifying the /cm option, for example:

Windows:

/cm cciipx

This entry in the Fileshare Server configuration file enables the Fileshare Server to communicate with Fileshare Clients using the Novell IPX (CCIIPX) protocol.

UNIX:

-cm ccitcp
-cm ccinampu

These entries in the Fileshare Server configuration file enable the Fileshare Server to communicate with Fileshare Clients using TCP/IP (CCITCP) and the Named Pipes for UNIX (CCINAMPU) protocol.

Parent topic: Configuring the Fileshare Server
Related information
Specifying a Fileshare Server Name
Fileshare Server Configuration Options


Fileshare Server Configuration Options

This section describes all of the available Fileshare Server configuration options. The /s option that defines the server-name is compulsory. All other options are optional or have default values that are specified below.

Note:
  • UNIX: In this section, options are shown starting with a forward slash (/). This is how you specify the options on Windows. On UNIX, use the hyphen (-) character instead of the forward slash.
  • UNIX: Filenames are shown using the Windows naming convention. On UNIX, use the UNIX file-naming conventions.
Server Configuration Options Specifying
/s server-name
 The name that the Fileshare Server registers on the network. This must be a character string up to 16 characters in length, depending on the CCI protocol that you are using. The name specified must be unique. If a Fileshare Server with the same name is already registered on the network, an error is returned.
/d database-reference-file
 The name of the database reference file that the Fileshare Server is to use. The database reference file is used to determine which additional Fileshare features you want to use.
/t timeout-period
 Setting the record lock timeout period after which the Fileshare Server releases all record locks held by a Fileshare Client and rolls back any outstanding transactions. The timeout period is specified in seconds. The default value is 60 seconds. Specifying a value of zero disables the timeout and record locks are only released under the control of your application program. Valid values are 0 thru 99999. The timeout only occurs if one Fileshare Client requests a record currently locked by another Fileshare Client.

Setting a value of zero in conjunction with setting the environment variable ES_RLS_FILE_SUPPORT=Y ensures that no information is returned to the record area following a READ operation on a locked record.

/m record-size
 The maximum record size that can be processed by the Fileshare Server. Setting a value lower than the default value reduces the amount of memory that the Fileshare Server needs to run. The record size is specified in kilobytes. Valid values are 16 thru 64. If you specify a value less than 16, the Fileshare Server uses a buffer size of 16K. If you specify a value greater than 64, the Fileshare Server uses a buffer size of 64K.
/cm cci-protocol
 The CCI protocols that the Fileshare Server can use. Repeat this option for every communications protocol that you want to use to contact this Fileshare Server. Valid values for cci-protocol are:

Windows: ccinetb ccitcp cciipx UNIX: ccitcp ccinampu

/pf password-file
 The name of the password file that the Fileshare Server uses.
/tr f
 Activating the Fileshare Server trace option on start-up. Trace messages are written to the screen and to a file called fsscreen.lst in the Fileshare Server's current directory. This option seriously impacts the Fileshare Server's performance, so you should only use it for problem investigation.
/sc
 Use this to get the best performance. Switching Fileshare into synchronous communications mode. This means that when there is nothing for Fileshare to process, it goes into a wait state until interrupted by a message from the communications layer. You need to use a password file, and provide a password for fsview so that you can shut down Fileshare remotely. You can shut it down from the screen, but you might need to wait up to two minutes before it responds to the screen action.
/ev event-emit
Indicates the types of error messages that are written to fsscreen.lst in order to cause events if you have Fileshare tracing enabled.
event-emit is any combination of IEWS, where
  • I = information
  • E = error
  • W = warning
  • S = severe
-b
 You must specify this if the Fileshare Server is to run as a background process. You can use it only on the command line.
/pt time
 Writes to fsscreen.lst details of processes that take longer than the time specified to complete. Time can be specified in 10ths of a second.
  • Example Server Configuration File
Parent topic: Configuring the Fileshare Server
Related information
Specifying a Fileshare Server Name
Specifying the Communications Protocol
Database Reference File Maintenance
Automatic Record Lock Timeout
Security
Monitoring Fileshare
Fileshare on UNIX


Example Server Configuration File

This example shows a typical Fileshare Server configuration file.

/s mainsrv
/cm cciipx
/d dbase1.ref
/t 120
/pf \pass\passwd.fil

where:

Line 1:
/s mainsrv

Specifies that the Fileshare Server is to register its name on the network as mainsrv. Fileshare Clients must specify this name when they want to contact this Fileshare Server.

Line 2:
/cm cciipx

Specifies that cciipx is one of the communications protocols that a Fileshare Client can use to contact this Fileshare Server.

Line 3:
/d dbase1.ref

Specifies that the database reference file the Fileshare Server is to use is named dbase1.ref.

Line 4:
/t 120

Specifies that the automatic record lock timeout period is 120 seconds.

Line 5:
/pf \pass\passwd.fil

Specifies that the Fileshare Password Security feature is enabled and that the password file is \pass\passwd.fil containing valid user-IDs and passwords.

Parent topic: Fileshare Server Configuration Options


Starting the Fileshare Server

You must start the Fileshare Server running before Fileshare Clients can connect to it.

To start the Fileshare Server use the following command line:

fs
Parent topic: Fileshare Server
Related information
Configuring the Fileshare Server
Stopping the Fileshare Server


Stopping the Fileshare Server

Once started, a Fileshare Server runs as an active process until you explicitly stop it. You must stop the Fileshare Server when you no longer need it. To do this, press the Escape key. Fileshare displays:

FS097-I Are you sure that you wish to close down the Fileshare Server?

Enter Y to confirm that you want Fileshare to terminate. Any other entry causes the Fileshare Server to continue running.

If any data files are still open, the following warning is displayed:

FS111-I Warning - files are still open
        Continue to close down the Fileshare Server (Y/N) ?

Enter Y to confirm that you want Fileshare to terminate. Fileshare automatically closes all data files and rolls back any outstanding transactions. Any other entry causes the Fileshare Server to continue running. This warning indicates one of the following:

  • Fileshare Clients are still active, with open data files
  • A user program terminated abnormally without closing the data files it had open

If you are using the CCITCP protocol and the Fileshare Server terminates abnormally, you can restart the Fileshare Server using the same server-name. However, Fileshare displays the warning message:

FS153-I The Fileshare Server name has been reregistered on the network.
Parent topic: Fileshare Server
Related information
Configuring the Fileshare Server
Starting the Fileshare Server


Configuring CCI Communications for Fileshare

This section describe how to configure the communications between Fileshare Client(s) and Fileshare Server(s). Fileshare clients and servers communicate using the Common Communications Interface (CCI).

  • About Fileshare Communications
  • Specifying the Communications Protocol
  • Using CCITCP
  • Using UNIX named pipes: ccinampu
  • Logging Fileshare Messsages: CCI Trace
  • Using Multiple Protocols with Test Programs
  • Configuring the CCI Timeout
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


About Fileshare Communications

A Fileshare Server communicates with a Fileshare Client using the Common Communications Interface (CCI). A Fileshare Server can use several communication protocols concurrently, enabling it to communicate with a number of Fileshare Clients that do not all use the same protocol.

When you invoke a Fileshare Server, you need to specify the communications protocols it supports, using the /cm option in the Fileshare configuration file. Valid values for /cm are:

Windows platform:

  • TCP IP

    Setting: /ccitcp

  • CCISMEM

    Setting: /ccism

UNIX platform:

  • TCP IP

    Setting: -ccitcp

  • UNIX named pipes (FIFO pipes)

    -ccinampu

When running the Fileshare Server and Fileshare Client on the same UNIX machine, use the Named Pipes protocol for UNIX (CCINAMPU) as this provides significantly better performance than CCITCP.

Parent topic: Configuring CCI Communications for Fileshare
Related information
Specifying the Communications Protocol
Using CCITCP
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using CCITCP

Fileshare defaults to the TCP/IP (CCITCP) protocol. When using CCITCP, you can use either CCITCP Direct or the following process:

  • Both the Fileshare Client and the Fileshare Server must have access to a registration process. Depending upon the product that has been installed there are two versions of the registration server called ccitcp2 or mfds the Micro Focus Directory Server.
  • The registration process helps the Fileshare Client to locate the Fileshare Server.
  • The registration process can be running on any machine that the Fileshare Client and Fileshare Server can contact. It does not have to be running on the same machine as either Fileshare Server or Fileshare Client.
  • You must set the environment variable CCITCP2 to the host name of the machine where the ccitcp2 process is running.

    If you do not set the environment variable, CCITCP assumes that ccitcp2 is running on the local machine. The Fileshare Client and the Fileshare Server must register with the same ccitcp2 process in order to communicate with each other.

    For example, consider the situation where the Fileshare Server and the Fileshare Client are running on different machines and the ccitcp2 process is running on the same machine as the Fileshare Server. The environment variable CCITCP2 does not have to be set on the machine running the Fileshare Server. However, it must be set (on the machine running the Fileshare Client) to the TCP/IP host name of the machine where the Fileshare Server (and the ccitcp2 process) is running.

  • By default both ccitcp2 and mfds will start on TCP (mfds only) and UDP port 86. Both registration processes may be started on different ports. If this has been done then you must set the environment variable CCITCP2_PORT to the decimal number of the port that is being used for the registration process.

    For example, consider the situation where mfds has been started with CCITCP2_PORT set to 2023, or using the -p 2023 option. You must set CCITCP2_PORT to 2023 on both the Fileshare Client and the Fileshare Server.

Many configuration options exist for CCITCP, details of these can be found in the comments within the CCI.INI configuration file.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using UNIX named pipes: ccinampu

Using UNIX named pipes (FIFO pipes)

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Logging Fileshare Messsages: CCI Trace

CCI Trace enables all the messages sent by CCI to be logged to a file. This can help in tracking down and debugging problems related to communications. To activate CCI Trace, add the following to the Fileshare Server configuration file:

/tr cci

To prevent unauthorized access to the CCI Trace information, you are prompted for the supervisor password when you invoke a Fileshare Server with CCI Trace enabled. If the password is accepted, CCI Trace is enabled and a second prompt asks if CCI Trace should be activated immediately or not.

Note:
  • The supervisor password is that specified for the user-ID FSVIEW in the password file, so you must specify the appropriate password file when you start the Fileshare Server.
  • CCI Trace can be toggled on and off using the F3 key.
  • The CCI trace options are specified via the CCITRACE environment variable.
Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
Using UNIX named pipes: ccinampu
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using Multiple Protocols with Test Programs

Switching between CCITCP protocol and CCISMEM protocol can affect test program timings.

Access to the driver levels usually results in the context switching out of the sending process quite soon after the send attempt has begun. Typically the peer process uses the CPU before the context switches back to the original process.

As a result, with CCITCP, more processing time is required at the driver level than with CCISMEM which has no driver application to call. When CCITCP moves to the drivers to execute the extra data moves, the context is switched out the parent process. On the other hand, using CCISMEM with the same send operation, no context switch occurs. The CCI caller manages when to switch to its peers.

When the configuration is set to async mode (the default) File Share polls CCI to determine if data is present to read. As a result, much more time in CPU processing is spent at the user level, waiting for the next buffer to process. The application and File Share do not context switch to the conversation peer until the end of a full time-slice. That is, the CPU cannot process the next chunk of data and to respond to the original sender until the end of a full time-slice.

This can often cause quite dramatic effects on heavily loaded single CPU systems, or dual/quad core systems, when using test application created with polling loops that have scrolling screen displays.

Highlighting windows and de-selecting them alters the time spent in clients and servers because it changes their system priorities and hence the amount of time that is spent polling around not yielding to let partner processes do their work.

In these cases the fastest route is always to not high-light either client or server, then they both get the same amount of CPU with the smallest time slice. Its a case of the processes running with too much CPU not too little.

The fastest design is of course to not loop at all, then you'll be in the right place to receive the in-bound data when it arrives, and to respond quickly without wasting any CPU cycles in redundant polling.

File share can be configured to avoid the polling loop.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Configuring the CCI Timeout


Configuring the CCI Timeout

By default, CCI waits 120 seconds for a network request to complete before it times it out and returns an error. If a network request has not completed in a period much shorter than this, it can usually be assumed that it is unnecessary to wait any longer. For example, if a Fileshare Server with the correct server-name is not active when a Fileshare Client attempts its first open, the application appears to hang for 120 seconds before a 9/124 status is returned because the server cannot be contacted. See the section Communications Errors in the chapter Error Handling for more details.

You can configure the Fileshare Client to use a shorter timeout period by using the /ct option in the client configuration file, fhredir.cfg. The timeout period is specified in 1/10th seconds.

For example:

/ct 300

This instructs the Fileshare Client to specify that CCI waits for 30 seconds for network requests to complete. After this time it returns a 9/124 status to the application program.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
Using UNIX named pipes: ccinampu
Logging Fileshare Messsages: CCI Trace
Using Multiple Protocols with Test Programs


Database Integrity

  • Transaction processing
  • Rollforward recovery
  • Database sequence numbering
  • Automatic database backup
  • Database reference file maintenance
  • Transaction Processing
  • Rollforward Recovery Logging
  • Rollforward Recovery Utility
  • Database Sequence Numbering
  • Automatic Database Backup and Rollforward Recovery
  • Database Reference File Maintenance
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Security
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Transaction Processing

Transaction processing enables you to group a set of data file updates together into one logical unit of work, known as a transaction. The changes you make as part of a transaction can be:

  • Permanently reflected in the data files by committing the work
  • Removed from the data files by rolling back the work. When a transaction is rolled back, the Fileshare Server returns the data files to the state they were in before the transaction started.

A transaction can include multiple updates to multiple data files on multiple Fileshare Servers.

A transaction starts when your program performs the first update operation (WRITE, REWRITE or DELETE) on a file which has the WITH ROLLBACK clause defined in its SELECT statement after:

  • The file is opened
  • A COMMIT or ROLLBACK statement is executed

A transaction terminates when:

  • A COMMIT verb is executed
  • A ROLLBACK verb is executed
  • The transaction is timed out. See the section Automatic Record Lock Timeout for further information.
Notes:

  • The COMMIT and ROLLBACK verbs release all the record locks held by a program on every data file. This does not depend on whether or not you specified the WITH ROLLBACK clause for a particular file.
  • The time taken to process a COMMIT or ROLLBACK operation is directly proportional to the number of updates performed in that transaction.
  • If you try to CLOSE a file that is participating in an active transaction, a 9/100 error status is returned and the file remains open. A COMMIT or ROLLBACK needs to be issued before the CLOSE can be executed.
  • When you use the WITH ROLLBACK clause, multiple record locking is implicitly defined on the file.

Before using transaction processing you are strongly advised to do the following to ensure the highest level of integrity for your data:

  • Include any file on which transaction processing is to be performed in the database reference file of the Fileshare Server that services the I/O requests for that file. See the section Database Reference File Maintenance for further information.
  • Specify a rollforward recovery log file in the database reference file. See the section Rollforward Recovery Logging for further information.

Record locks are implicitly obtained on every record that is updated in a transaction. If a transaction is temporarily suspended, for example, if your program requests input and the user is not responding, record locks can remain in the file for a considerable length of time. If another Fileshare Client tries to access the locked records, and a specified length of time has passed, the Fileshare Server aborts (rolls back) the transaction. When this happens, the transaction is said to be timed out by the Fileshare Server. See the section Automatic Record Lock Timeout for further information.

Note:

By keeping the number of updates performed in a transaction to a minimum, the number of record locks obtained is also kept to a minimum. This reduces the number of record locking conflicts between Fileshare Clients sharing the data, and increases the speed of any subsequent COMMIT or ROLLBACK operations.

  • Automatic Record Lock Timeout
  • Transaction Processing - Fileshare Client
  • Transaction Processing - Fileshare Server
Parent topic: Database Integrity
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility
Database Sequence Numbering
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance
Automatic Record Lock Timeout
Database Reference File Maintenance
Rollforward Recovery Logging


Automatic Record Lock Timeout

In a multi-user environment where files are being shared, programs use record locks to control concurrent access to individual records. In addition, Fileshare automatically obtains a record lock on any record that it updates within a transaction. The larger the number of record locks being held, however, the less concurrent access to data is possible. It is beneficial, therefore, for any one program to keep the number of record locks that it holds at any one time to a minimum.

If a Fileshare Client obtains a lock on a record (either explicitly or because it updated the record within a transaction) and a second Fileshare Client tries to read the locked record, the Fileshare Server checks to see how long it is since the Fileshare Client holding the record lock last contacted the Fileshare Server. If this period is:

  • Greater than the timeout period, the Fileshare Server:
    • Automatically rolls back any pending transaction being carried out by the first Fileshare Client
    • Releases all the record locks held by the first Fileshare Client
    • Returns error 9/068 "record locked" to the Client trying to read the record. Retrying the operation succeeds in gaining access to the record because the lock has now been released.
  • Less than the timeout period, the Fileshare Server returns error 9/068 "record locked" to the Fileshare Client trying to read the record

The default timeout period is 60 seconds. You can change this value using the /t option in the Fileshare Server configuration file. Specifying a value of zero disables the automatic record lock timeout such that record locks are only released under application program control.

A program that is timed out receives error 9/125 on its next I/O operation. You should treat this as a warning message and repeat the operation on which the error was returned. The Fileshare Server rolls back any active transaction and releases all the record locks held by the program that timed out.

Parent topic: Transaction Processing
Related information
Transaction Processing - Fileshare Client
Transaction Processing - Fileshare Server


Transaction Processing - Fileshare Client

For each data file on which you want transaction processing active, use the WITH ROLLBACK clause when you define the data file using the SELECT statement in your COBOL program.

For example:

select test-file assign to "test.dat"
   organization indexed
   record key prime-key
   lock mode manual with rollback
   ...

This sample code specifies that transaction processing is active on the file test.dat.

In your program, use the COMMIT verb to make the updates in a transaction permanent. Use the ROLLBACK verb to remove the updates in a transaction from the data files.

The COMMIT and ROLLBACK verbs work on all data files involved in a transaction. This means that you cannot check the status of the COMMIT or ROLLBACK operation using the file status of any one data file. Instead, you must call the File Handling Redirector module to check the status of the COMMIT or ROLLBACK. The entry point to call in the the File Handling Redirector module module is fs_status. The format of the call is:

call "fs_status" returning t-status
end-call

where t-status is defined as:

01 t-status  pic x(2) comp-x.

A non-zero value returned in t-status indicates that the COMMIT or ROLLBACK operation failed.

For example:

1   SELECT test-file ASSIGN TO "test.dat"
2      LOCK MODE MANUAL WITH ROLLBACK
3   ...
4   OPEN I-O test-file
5   ...
6   move 1 to prime-key
7   WRITE test-file-record
8   ...
9   COMMIT
10   call "fs_status"
11      returning t-status
12   end-call
13   if t-status < > 0
14      display "Warning - Commit operation failed"
15   end-if
16   move 2 to prime-key
17   WRITE test-file-record
18   ...
19   ROLLBACK
20   call "fs_status"
21      returning t-status
22   end-call
23   if t-status < > 0
24      display "Warning - Rollback operation failed"
25   end-if
26   WRITE test-file-record
27   ...

where:

Lines 1 - 2:
SELECT test-file ASSIGN TO "test.dat"
   LOCK MODE MANUAL WITH ROLLBACK

Specifies transaction processing for this data file.
Line 7:
WRITE test-file-record

Starts a new transaction.
Line 9:
COMMIT

Makes the updates to test-file permanent and terminates the transaction.
Lines 10 - 15:
call "fs_status"
   returning t-status
end-call
if t-status < > 0
   display "Warning - Commit operation failed"
end-if

Checks the status of the COMMIT operation.
Line 17:
WRITE test-file-record

Starts a new transaction.
Line 19:
ROLLBACK

Removes the updates made to test-file and terminates the transaction.
Lines 20 - 25:
call "fs_status"
   returning t-status
end-call
if t-status < > 0
   display "Warning - Rollback operation failed"
end-if

Checks the status of the ROLLBACK operation.
Line 26:
WRITE test-file-record

Starts a new transaction.

You do not need to change the configuration of the Fileshare Client to enable transaction processing.

Parent topic: Transaction Processing
Related information
Automatic Record Lock Timeout
Transaction Processing - Fileshare Server


Transaction Processing - Fileshare Server

You do not need to change the configuration of the Fileshare Server to enable transaction processing. However, if you recover a data file using the Rollforward Recovery Utility, any outstanding transactions at the end of the recovery process are implicitly rolled back. See the section Rollforward Recovery Utility for further information.

Parent topic: Transaction Processing
Related information
Automatic Record Lock Timeout
Transaction Processing - Fileshare Client
Rollforward Recovery Utility


Rollforward Recovery Logging

A system failure can result in loss of data in either of the following circumstances:

  • The Fileshare Server's cache or operating system's cache is not written to disk
  • The system failed while updating a file. In this case, the integrity of the files cannot be guaranteed

Rollforward recovery logging is the method used by Fileshare to store all the updates made to your data files in one or more log files. If your system fails, resulting in loss of data, the Rollforward Recovery Utility together with the log file(s) can be used to re-apply the updates to a back-up copy of the original data files. When the recovery is complete, the files contain the data they contained at the time of the system failure (with any outstanding transactions rolled back).

You do not need to make any changes to the Fileshare Client in order to use rollforward recovery logging.

  • Rollforward Recovery Logging - Fileshare Server
Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Utility
Database Sequence Numbering
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance


Rollforward Recovery Logging - Fileshare Server

To log updates to one or more files you need to create a database reference file containing the name of the file(s) for which updates are to be logged, and the name of the log file. See the section Database Reference File Maintenance below for details on creating database reference files.

You do not need to include an extension when you specify the log file name as this is generated automatically by the Fileshare Server. If you do specify an extension, the following message is displayed:

FS180-W The log filename specified has an extension. The name of the
log file has been changed to "filename".

During the logging process the Fileshare Server creates one or more recovery log files. The first recovery log file is called a starter log file, and subsequent log files are called continuation log files. The Fileshare Server creates a continuation log file whenever the current log file is backed up.

The current recovery log file always has an extension beginning with the character "L". A recovery log file that has been backed up has an extension beginning with the character "B". Following either of these letters is a two digit number indicating the recovery log file number, starting at 01. These automatically generated extensions indicate the order in which the log files were written, and hence the order in which they should be applied if a rollforward recovery is performed. For example, suppose you specify a log file called recover. When the Fileshare Server starts up it creates a log file called recover.L01 and logs updates in this file. If the recovery log file is backed up, the Fileshare Server renames the current log file recover.B01 and creates a new one called recover.L02. If the Fileshare Server is shut down, there would be two recovery log files: recover.B01 is called the starter log file and recover.L02 is a continuation log file. There is only ever one starter log file, but there can be any number of continuation log files.

When performing a recovery operation, the Rollforward Recovery Utility processes the starter log file first and then the continuation log files in the order in which they were created.

Updates to data files with entries in the database reference file are logged unless you explicitly turn logging off:

  • To add a data file entry to the database reference file, use the /f option of the Database Reference File Maintenance Utility
  • To turn logging off for a particular data file, use the "/o l" (omit logging) option when you add the filename entry to the database reference file

Because of the caching used by some operating systems, not all of the information written to the log file is physically written to disk. The Fileshare Server periodically calls the operating system to force the log file updates to be written. By default, the log file is flushed after every 100 records are written to the log file. You can configure this interval using the /lc (log count) option when you add the log file name to the database reference file. If you specify a log count of zero, the Fileshare Server does not make any calls to the operating system to flush the updates to disk. Instead, the operating system controls the flushing of the log file to disk.

The log file updates are also flushed to disk after every COMMIT operation.

If a transaction was pending at the time of a system failure, the Rollforward Recovery Utility implicitly rolls back the transaction when the files are recovered.

Rollforward recovery logging can severely affect performance. You can use the "/o l" option in the database reference file to switch logging off for those files for which this feature is not essential. Alternatively, you can omit entries for these files from the database reference file altogether.

The recommended method of using recovery logging is:

  1. Each time you want to take a backup of your data files (preferably every day), shut down the Fileshare Server. The Rollforward Recovery Log file(s) contains information about every update made to your database files since the Fileshare Server was started.
  2. Now take a backup of your data files. Once you have backed up your data files, the log file(s) is obsolete (because you only need to log the updates since your last backup) and can be deleted.
  3. Restart the Fileshare Server. It creates a new log file, and any further updates to the files in the database are logged in this new file. In the event of data loss due to a system failure, you can restore your latest database backup and re-apply the updates recorded in the log file(s) using the Rollforward Recovery Utility.
Note:

You can have the Fileshare Server automatically perform this sequence of operations for you by specifying a backup directory in the database reference file. See the section Automatic Database Backup and Rollforward Recovery.

If you have a large number of updates being logged, the log file can grow very large. If the disk where the log file resides were to become full, the ability to write records to the log file could be lost. This would result in an incomplete log file forcing the Fileshare Server to close down. A warning is displayed when the amount of free disk space for the log file drops below a certain percentage of the total disk. You can configure this percentage using the /p database reference file option. When you see this warning, close down the Fileshare Server and take a new backup of your data files. This enables you to discard the log file and continue with a new one when the Fileshare Server is restarted.

If you ignore the warning message and the log file continues to grow larger, the Fileshare Server suspends operation when the free disk space available for the log file drops below 200,000 bytes. It displays error message FS030 and waits for the old log file to be backed-up remotely or removed manually before continuing with a new log file.

Parent topic: Rollforward Recovery Logging
Related information
Database Reference File Maintenance
Automatic Database Backup and Rollforward Recovery


Rollforward Recovery Utility

The Rollforward Recovery Utility enables you to recover updates to data files after a system failure.

Note:

The Rollforward Recovery Utility can only be used to recover a database if the updates were logged to a recovery log file. See the section Rollforward Recovery Logging for further details.

Before attempting the rollforward recovery process:

  • All of the recovery log files created while the Fileshare Server was active should be in the recovery log file directory (or the log file backup directory if one is specified in the database reference file)
  • The original data files (the back-up versions taken before the Fileshare Server was started) should be restored to their correct directories

Use the /r (recover) option to invoke the Rollforward Recovery Utility. You must specify a database reference file when invoking the Rollforward Recovery Utility, for example:

fs /r dbase.ref [options]

Here dbase.ref is the name of the database reference file used by the Rollforward Recovery Utility. This must be the same as the database reference file used by the Fileshare Server while it was running. The Rollforward Recovery Utility reads the database reference file to determine the location and name of the rollforward recovery log file(s) and the name(s) of the data file(s) to recover.

Note:

You can select the data files you want to restore by erasing other entries from the database reference file using the Database Reference File Maintenance Utility (/e option) before invoking the Rollforward Recovery Utility.

You can use the Rollforward Recovery Utility to specify the following options:

  • /dt date-time

    Specifies that the Rollforward Recovery Utility restores the updates made to the data files up to the time specified. The format of date-time is YYMMDDHHMMSS (year, month, day, hour, minutes, seconds) specified numerically. When you do not specify this option, the Rollforward Recovery Utility applies all of the updates that are stored in the rollforward recovery log file.

    For example:

    fs /r dbase.ref /dt 931231235959

    invokes the Rollforward Recovery Utility using the database reference file dbase.ref. Only those updates that were made up to the end of 31 December 1993 are restored.

  • /v

    Causes the Rollforward Recovery Utility to display additional information about which recovery log files it is searching for and in which directories.

Updates can be recorded in multiple log files (see the section Rollforward Recovery Logging for further details). The Rollforward Recovery Utility scans the log file directory for the starter log file. If none is found, the directory is scanned for a backed-up starter log file. If a starter log file still cannot be found the same procedure is repeated with the searches being performed in the backup directory if one is specified in the database reference file. If the Rollforward Recovery Utility is able to locate the starter log file then the recovery procedure commences; if not an error is displayed and the recovery does not start.

Once the starter log file has been processed, the Rollforward Recovery Utility searches for a continuation log file. If no backup of the recovery log file was performed, there is no continuation log file and the recovery process terminates. The Rollforward Recovery Utility searches for the continuation log file in the log file directory and then in the log file backup directory. The recovery process continues using the continuation log file(s) until all of the updates have been recovered and applied to the data files.

If transactions were in progress when the server terminated, then these transactions will be recorded but not committed. In addition, if the server was forced to terminate, then all open files will record a close, even if they were in mid transaction. A rollforward recovery will not be able to commit these transactions and a subsequent normal close would be illegal. When this situation occurs, the user will be informed with the message:

FS290-W Uncommitted transaction recorded - cannot complete transaction.

followed by the name of the file that cannot complete the transaction.

Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Logging
Database Sequence Numbering
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance
Rollforward Recovery Logging


Database Sequence Numbering

Database sequence numbering provides a method of linking groups of data files so that they and their corresponding log file can be kept in step.

A sequence number, contained in the log file, is automatically stored in the header of each data file for which you have specified sequence numbering. Fileshare increments these sequence numbers every time you invoke the Fileshare Server. In order for the Rollforward Recovery Utility to work, all data files must have sequence numbers that match the log file. If the sequence numbers in the data files do not match, the Fileshare Server fails to start after displaying this message:

FS038-S A matching sequence number not found in <filename>

The possible causes for this error are:

  • A data file has been replaced by a file that does not contain the same sequence number as all the other data files listed in the database reference file. To recover, you need to install the correct file(s) on the system.
  • A power failure prevented proper shutdown of the Fileshare Server when it was last running. To recover the database files, use rollforward recovery. See the section Rollforward Recovery Utility for further information.

All data files listed in the database reference file have sequence number checking active by default. You can turn off sequence number checking using the database reference file option "/o s" (omit sequence numbering). If sequence number checking is not used on a file, your system administrator must make sure that the correct version of the file is installed in the Fileshare System.

Sequence numbering is only available on data files with a variable length record file header. The following file organizations do not contain headers and so sequence number checking is not possible:

  • Line sequential files
  • Non-data-compressed fixed length record sequential files
  • C-ISAM files
  • Non-data-compressed fixed length record relative files

If you have fixed length record data files that you want to use sequence numbering on, create them as variable length record data files. You can do this by changing the file definition in your COBOL program before creating the file.

Example

Data file definition specifying fixed length records:

 FD account-file.
 01 account-file-record.
    03 account-file-prime pic x(4).

Equivalent data file definition specifying variable length records:

 FD account-file recording mode is variable.
 01 account-file-record.
    03 account-file-prime pic x(4).

You do not have to change the configuration of the Fileshare Client or your program to make use of database sequence numbers.

  • Database Sequence Numbers - Fileshare Server
Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Logging
Rollforward Recovery Utility
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance
Rollforward Recovery Utility


Database Sequence Numbers - Fileshare Server

For data files that you entered in the database reference file, sequence number checking is on by default. If you do not need sequence number checking for a particular data file, you can disable the feature by using the /o s (omit sequence numbers) option for that data file's entry in the database reference file.

Example

Windows:

fs /d dbase.ref /l \logdir\log.dat
fs /d dbase.ref /f test1.dat
fs /d dbase.ref /f test2.dat /o l
fs /d dbase.ref /f test3.dat /o s

UNIX:

fs -d dbase.ref -l /logdir/log.dat
fs -d dbase.ref -f test1.dat
fs -d dbase.ref -f test2.dat -o l
fs -d dbase.ref -f test3.dat -o s

This example specifies:

  • The database reference file is named dbase.ref
  • The log file is named log.dat in the logdir directory
  • Updates to the data file test1.dat are logged in the log file. By default, sequence number checking is on for any data file in the database reference file, and hence for this file
  • Updates to the data file test2.dat are not logged in the log file. The "/o l" option specifies that logging is omitted. However, sequence number checking is still active for this file.
  • Updates to the data file test3.dat are logged in the log file. However, sequence number checking is not activated for this data file. The "/o s" option specifies that sequence number checking is not used on this data file.
Parent topic: Database Sequence Numbering


Automatic Database Backup and Rollforward Recovery

The recommended method of using Fileshare's update logging for rollforward recovery is:

  1. Periodically to shut down the Fileshare Server
  2. Take a backup of all your database files
  3. Re-start the Fileshare Server with a fresh recovery log file

See the section Rollforward Recovery Logging for further details.

You can get Fileshare to do this for you automatically by specifying a backup directory-name in the database reference file using the /backup option. For example, the command:

Windows:

fs /d dbase.ref /backup	c:\backdir

UNIX:

fs /d dbase.ref /backup	/backdir

adds an entry to the database reference file called dbase.ref which specifies the backup directory as c:\backdir on Windows or /backdir on UNIX. A full path can be specified for the backup directory, otherwise paths which are not fully qualified are taken to be relative to the current directory of the Fileshare Server.

Setting a backup directory in this way causes the Fileshare Server to copy all the data files specified in the database reference file to the directory c:\backdir or /backdir on startup. The Fileshare Server also deletes any recovery log file(s) that it finds since this data is obsolete once the database files have been backed up.

While the Fileshare Server is active, all updates to files which have logging switched on for them are recorded in the log file as normal. The next time the Fileshare Server is restarted, it backs up the database files again and discards any log file(s). However, if it detects that the previous Fileshare Server session did not shut down successfully and a valid terminating record had not been written to the log file (for example, as a result of a system crash), then Fileshare automatically triggers the Rollforward Recovery Utility. This automatically restores the previous backup of the database files and recovers all updates to them as recorded in the log file(s). If the recovery completes succesfully, the Fileshare Server starts up as normal.

It is still possible to run the Rollforward Recovery Utility manually before starting up the Fileshare Server when a backup directory is specified in the database reference file. The Rollforward Recovery Utility automatically restores the previous backup before initiating the recovery.

Note:

The purpose of the automatic database backup facility is to help database administrators follow the recommended steps for rollforward recovery, thus ensuring that the latest Fileshare log file contains only the updates made since the last database backup. If database files are added or replaced manually, Fileshare may not detect this and could backup or restore the incorrect version of a file, compromising the integrity of your data. We recommend, therefore, that you do not attempt to replace any of the database files manually and only ever use Fileshare operations such as closing down the server to back up the entire database.

If you have enabled automatic database backup by specifying a backup directory, you cannot use the "/o l" option to switch logging off for any of the data files declared in the database reference file. By having logging active for every file specified in the database reference file, Fileshare can guarantee that it can recover updates to them all when it copies backed-up versions from the backup directory. If there are some files for which you do not require automatic backup, omit them from the database reference file.

If you need to back up your Fileshare files, for example as part of a system-wide backup overnight, you can use a Fileshare Manager API function to request Fileshare to shut down, back up all the database files and then restart with a fresh log file. Having done this, we recommend that you then make a permanent hard copy of the Fileshare backup directory. See the section Fileshare Manager in the chapter Advanced Operation for more information.

Example

Windows:

fs /d dbase.ref /l logfile
fs /d dbase.ref /backup c:\backdir
fs /d dbase.ref /f c:\accounts\customer.dat
fs /d dbase.ref /f c:\finance\history.dat

UNIX:

fs /d dbase.ref /l logfile
fs /d dbase.ref /backup /backdir
fs /d dbase.ref /f /accounts/customer.txt
fs /d dbase.ref /f /finance/history.txt

These commands perform the following:

  • Create a database reference file called dbase.ref
  • Specify the recovery log file as logfile so that the first log file that the Fileshare Server creates is called logfile.L01
  • Specify that any updates to the files c:\accounts\customer.dat and c:\finance\history.dat on Windows, or /accounts/customer.txt and /finance/history.txt on UNIX, are logged
  • Specify c:\backdir on Windows or /backdir on UNIX as the backup directory

On startup, the Fileshare Server automatically backs up these data files in the directory c:\backdir or /backdir. If the log file is backed-up while the Fileshare Server is active, backup files are also placed in this directory. If the Rollforward Recovery Utility is invoked, the backup files in c:\backdir or /backdir are restored to their original directories and any updates recorded in the log file(s) are re-applied.

Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Logging
Rollforward Recovery Utility
Database Sequence Numbering
Database Reference File Maintenance
Rollforward Recovery Logging
Fileshare Manager


Database Reference File Maintenance

The database reference file contains information that the Fileshare Server uses to determine which Fileshare features you want to use on which files. This section explains how to create and update a database reference file in order to make use of the features described earlier in this chapter.

Note:
  • You should only create or change a database reference file using the Database Reference File Maintenance Utility. This is because the file contains information that is stored in a special format.
  • UNIX: In this section, options are shown starting with a forward slash (/). This is how you specify the options on Windows. On UNIX, use the hyphen (-) character instead of the forward slash.
  • UNIX: Filenames are shown using the Windows naming convention. On UNIX, use the UNIX filenaming conventions.

The Database Reference File Maintenance Utility is invoked using the /d (database) option, for example:

fs /d dbase.ref [options]

where the parameters are:

dbase.ref | Name of the database reference file. If the database reference file does not exist, it is created.
options | These specify the operation to be carried out on the database reference file. Each initiation of the Database Reference File Maintenance Utility adds a record to or removes a record from the database reference file specified.

You can add several types of record to the database reference file.

  • Recovery Log File Records
  • Filename Record
  • File String Record
  • Backup Folder Record
Parent topic: Database Integrity
Related information
Transaction Processing
Rollforward Recovery Logging
Rollforward Recovery Utility
Database Sequence Numbering
Automatic Database Backup and Rollforward Recovery


Recovery Log File Records

You specify the name of the recovery log file using the /l option, for example:

fs /d dbase.ref /l logfilename

You can only have one recovery log file record in a database reference file.

You can specify the following for a recovery log file record:

  • The point at which the Fileshare Server displays a warning when the drive containing the log file is becoming full (use the /p option)
  • How often the log file is flushed to disk (use the /lc option)
  • Deletion of the record (use the /e option)
  • Disk Space Warning (/p)
  • Flushing the Log File (/lc)
  • Erasing a Log File Record (/e)
  • Example
Parent topic: Database Reference File Maintenance
Related information
Filename Record
File String Record
Backup Folder Record


Disk Space Warning (/p)

You can specify the point at which the Fileshare Server displays a warning when the drive containing the log file is becoming full using the /p option:

fs /d dbase.ref /l logfilename /p nnn

where nnn specifies the percentage disk space remaining, below which the Fileshare Server displays a warning message. The default value is 5, that is, the Fileshare Server displays the warning message when the drive containing the log file contains less than 5% free space.

Parent topic: Recovery Log File Records
Related information
Flushing the Log File (/lc)
Erasing a Log File Record (/e)
Example


Flushing the Log File (/lc)

You can specify how often the log file is flushed to disk using the /lc option:

fs /d dbase.ref /l logfilename /lc nnn

where nnn specifies the number of records that are written to the log file before the Fileshare Server calls the operating system to flush the log file buffers to disk. The default value is 100, that is, the Fileshare Server flushes the log file to disk after each set of 100 records are written to it. In addition, the Fileshare Server automatically flushes the log file after every successful COMMIT operation.

The Fileshare Server is unable to flush a log file if the log file is not on the machine where the Fileshare Server is running or if the operating system does not allow Fileshare to force the log file to be flushed. In this situation, the "/lc 1" option forces the Fileshare Server to specify writethrough when opening the log file. The log file is then written to disk if the operating system supports writethrough on files.

Parent topic: Recovery Log File Records
Related information
Disk Space Warning (/p)
Erasing a Log File Record (/e)
Example


Erasing a Log File Record (/e)

You can erase a recovery log file record using the /e option:

fs /d dbase.ref /l logfilename /e

This is the only way to remove a record once you have created the database reference file.

Parent topic: Recovery Log File Records
Related information
Disk Space Warning (/p)
Flushing the Log File (/lc)
Example


Example

fs /d dbase.ref /l \log\log.dat /p 10 /lc 200

Specifies the log file as log.dat in the directory log. Any data files that are specified in this database reference file have all updates recorded in this log file, unless logging is explicitly disabled for a data file. The /p option specifies that the Fileshare Server displays a warning message when less than 10 percent of the disk space remains free on the drive where the log file resides. The /lc option specifies that the Fileshare Server flushes the log file to disk after every 200 records are written to it.

Parent topic: Recovery Log File Records
Related information
Disk Space Warning (/p)
Flushing the Log File (/lc)
Erasing a Log File Record (/e)


Filename Record

You specify a filename record using the /f option, for example:

fs /d dbase.ref /f filename

specifies a data file that you want to include in the database reference file.

Any file that you specify in the database reference file has logging and, for those file organizations that support it, database sequence numbering, enabled by default.

You can specify the following for a filename record:

  • An alternative filename (use the /af option)
  • A virtual file handler (use the /ap option)
  • Data and key compression (use the /k option)
  • That logging is disabled for this file (use the "/o l" option)
  • That database sequence numbering is disabled for this file (use the "/o s" option)
  • That transaction processing is disabled for this file (use the "/o t" option)
  • Deletion of the record
  • Alternative Filename (/af)
  • Virtual File Handler (/ap)
  • Data and Key Compression (/k)
  • Disable Logging (/o l)
  • Disable Database Sequence Numbering (/o s)
  • Disable Transaction Processing (/o t)
  • Erasing a Filename Record
  • Examples
Parent topic: Database Reference File Maintenance
Related information
Recovery Log File Records
File String Record
Backup Folder Record


Alternative Filename (/af)

You can specify an alternative filename for a filename record using the /af option:

fs /d dbase.ref /f filename /af alternate-filename

such that whenever the Fileshare Server is asked to access the data file filename, it accesses alternate-filename instead.

Parent topic: Filename Record
Related information
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Virtual File Handler (/ap)

You can specify a virtual file handler for a filename record using the /ap option:

fs /d dbase.ref /f filename /ap program-name

where program-name specifies the virtual file handler that the Fileshare Server calls to process all I/O requests on the data file. See the section Virtual File Handler in the chapter, Advanced Operation.

The filename definition in the /f entry (corresponding to an /ap entry) can include a trailing wildcard to specify that groups of files are to have their requests passed to the specified virtual file handler.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Data and Key Compression (/k)

You can specify data and key compression for a filename record using the /k option, for example:

fs -d dbase.ref /f filename /k DnnnIx

where nnn specifies the data compression routine number and x specifies the key compression number. Valid values for nnn and x are the same as those that can be specified for the Compiler directives DATACOMPRESS and KEYCOMPRESS.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Disable Logging (/o l)

You can disable logging for a file using the "/o l" option:

fs /d dbase.ref /f filename /o l

disables logging for filename.

Note:

You cannot disable logging for a file if you have enabled automatic database backup by specifying a backup directory record.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Disable Database Sequence Numbering (/o s)

You can disable database sequence numbering for a file using the "/o s" option:

fs /d dbase.ref /f filename /o s
disables database sequence numbering for filename.
Note:

You should be aware that even with database sequence checking turned off, Fileshare will still update the sequence number in the header of the data file and thus also the timestamp. This is to ensure that if sequencing is turned back on, the sequence numbers will be in sync with other files.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Transaction Processing (/o t)
Erasing a Filename Record
Examples


Disable Transaction Processing (/o t)

You can disable transaction processing for a file using the "/o t" option:

fs /d dbase.ref /f filename /o t

disables transaction processing for filename. The WITH ROLLBACK clause in a SELECT statement for this data file is ignored. This option in the database reference file overrides any transaction processing specified in your program.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Erasing a Filename Record
Examples


Erasing a Filename Record

You can erase a filename record using the /e option, for example:

fs /d dbase.ref /f filename /e

erases the record from the database reference file. This is the only way to remove a record once the database reference file has been created.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Examples


Examples

fs /d dbase.ref /f \accounts\nomlgr.dat /k d001i7

specifies that the data file nomlgr.dat in the directory accounts has data compression and key compression activated if it is created by the Fileshare Server. The d001 option specifies the data compression routine you want to use is the same as if you compiled your program with the DATACOMPRESS"1" Compiler directive. The i7 option specifies the key compression to use is the same as if you compiled your program with the KEYCOMPRESS"7" Compiler directive. This overrides any data or key compression specified in the program.

fs /d dbase.ref /f \accounts\salesday.dat /o tl

specifies that any transaction processing specified in your program for the data file salesday.dat in the directory accounts is ignored. Also, logging is disabled for this file.

fs /d dbase.ref /f \ref\clients.dat /af \oldref\oldclnts.dat /o s

specifies that all I/O requests for the data file clients.dat in the directory ref are redirected to the data file oldclnts.dat in the directory oldref. In addition, database sequence numbering is disabled for this file.

fs /d dbase.ref /f \accounts\saleslgr.dat

enables logging and database sequence numbering for the data file saleslgr.dat in the directory accounts. By default, logging and database sequence numbering are enabled for every data file listed in the database reference file.

fs /d dbase.ref /f \orders\week10.dat

enables logging and database sequence numbering for the data file week10.dat in the directory orders. By default, logging and database sequence numbering are enabled for every data file listed in the database reference file.

Parent topic: Filename Record
Related information
Alternative Filename (/af)
Virtual File Handler (/ap)
Data and Key Compression (/k)
Disable Logging (/o l)
Disable Database Sequence Numbering (/o s)
Disable Transaction Processing (/o t)
Erasing a Filename Record


File String Record

You specify a file string record using the /fs option, for example:

fs /d dbase.ref /fs string1 /af string2

specifies that for any data file with a filename starting with string1, string1 is replaced by the character string string2.

  • Erasing a File String Record
  • Example
Parent topic: Database Reference File Maintenance
Related information
Recovery Log File Records
Filename Record
Backup Folder Record


Erasing a File String Record

You can erase a file string record using the /e option:

fs /d dbase.ref /fs string /e

erases the record from the database reference file. This is the only way to remove a record once the database reference file has been created.

Parent topic: File String Record
Related information
Example


Example

fs /d dbase.ref /fs c:\accounts\ /af c:\lastyear\accounts\

specifies that the character string c:\accounts\ at the front of any filename is replaced by the character string c:\lastyear\accounts\. Note that the string specified by the /fs option is not expanded relative to the Fileshare Server's current directory.

Parent topic: File String Record
Related information
Erasing a File String Record


Backup Folder Record

You specify an automatic backup directory using the /backup option, for example:

fs /d dbase.ref /backup c:\backup

specifies that on startup the Fileshare Server automatically copies all of the files named in the database reference file into the directory c:\backup.

Parent topic: Database Reference File Maintenance
Related information
Recovery Log File Records
Filename Record
File String Record


Security

You can also restrict access to specific data files under the control of a Fileshare Server. These restrictions are implemented via:
  • The Fileshare Password System
  • The Logon Validation module
  • The File Access Validation module
  • Password System
  • Logon Validation Module
    To validate a request to log on from a Fileshare Client, the Fileshare Server calls the module FSSecLog (the Fileshare Security at Logon Validation module) to validate the user-ID and password. You can replace FSSecLog with your own module in order to use your own criteria for validating the log on request. Your new module must comply with the FSSecLog interface described below.
  • File Access Validation Module
    To validate an open request from a Fileshare Client, the Fileshare Server calls the Fileshare Security at Open Validation module (FSSecOpn).
  • Password File Maintenance
  • User-ID Groups
  • Supervisor Mode
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Advanced Operation
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Password System

If you invoke the Fileshare Server with the Password System enabled, all Fileshare Clients must supply a valid user-ID and password before they can connect to the Fileshare Server. By default, the Fileshare Password System is not enabled when you invoke the Fileshare Server.

If you want to use the Fileshare Password System you must code your program to pass a user-ID and password to the File Handling Redirector module and you must create a password file on the Fileshare Server machine which contains the user-ID and password that your program will use.

Then, to enable the Fileshare Password System, you must use the /pf option to specify the name of the password file to the Fileshare Server.

With the Fileshare Password System enabled, the sequence of steps that your program and Fileshare follow is (see the figure below):

  1. Your program registers its user-ID and password with the Fileshare Client by calling the File Handling Redirector password module (FHRdrPwd)
  2. Your program performs the first I/O operation
  3. The File Handling Redirector module obtains the user-ID and password registered in step 1 by calling the File Handling Redirector password module (FHRdrPwd)
  4. File Handling Redirector module passes the user-ID and password to the Fileshare Server
    Figure 1. Fileshare Password System
    Fileshare Password System
  5. The Fileshare Server validates the user-ID and password using the password file.
  6. If the Fileshare Server allows the logon, a connection is established between the Fileshare Client and the Fileshare Server. If the Fileshare Server does not allow logon, it returns a file status of 9/037 ("access denied") to the Fileshare Client.

Each of these steps is explained in more detail in the topics that follow.

  • Fileshare Client
  • Fileshare Server
  • Writing Your Own FHRdrPwd Module
Parent topic: Security
Related information
Logon Validation Module
File Access Validation Module
Password File Maintenance
User-ID Groups
Supervisor Mode


Fileshare Client

When Fileshare security is active, your program must supply a user-ID and a password before the first I/O operation is performed.

Even if you have not activated security, your program can still supply the Fileshare Client with a user-ID and password. This enables your program to run unchanged on Fileshare whether or not security is activated.

To register a user-ID and password, your program must call the module FHRdrPwd as follows:

call "fhrdrpwd" using function-code,
                      user-ID,
                      user-password
end-call

where the parameters are:

01 function-code       pic x comp-x.
01 user-ID             pic x(20).
01 user-password       pic x(20).

The function code to register a user-ID and password is 1.

The following example shows how to register a user-ID and password:

working-storage section.
01 function-code    pic x comp-x.
01 user-name        pic x(20).
01 user-password    pic x(20).
...
procedure division.
...
    move 1 to function-code
    move "UserID" to user-name
    move "Password" to user-password
    call "fhrdrpwd" using function-code,
                        user-name,
                        user-password
    end-call
    ...
    open output testfile
    ...

You can substitute the FHRdrPwd module supplied with the Fileshare System with your own. This enables you to retrieve the user-ID and password from somewhere other than the application program. See the section Writing Your Own FHRdrPwd Module for further details.

Parent topic: Password System
Related information
Fileshare Server
Writing Your Own FHRdrPwd Module
Writing Your Own FHRdrPwd Module


Fileshare Server

By default, the Fileshare Password System is not active when you invoke the Fileshare Server. If you want password security activated, use the /pf (Password File) option in the Fileshare Server configuration file, for example:

Windows:

/pf password.fil /s server1

UNIX:

-pf password.fil -s server1

specifies that for the Fileshare Server, server1, Fileshare Password Security is enabled and the password file is password.fil. The Fileshare Server uses this file to determine whether a Fileshare Client is allowed to connect to this Fileshare Server.

The Password File Maintenance Utility is used to create the password file and add user-ID and password entries. See the section Password File Maintenance for further information on this utility.

Parent topic: Password System
Related information
Fileshare Client
Writing Your Own FHRdrPwd Module
Password File Maintenance


Writing Your Own FHRdrPwd Module

To register a user-ID and password, your program must call the File Handling Redirector password module supplying a user-ID and password. If you do not want to hard-code this call into your program, you can replace the supplied File Handling Redirector password module with one that obtains the user-ID and password using a different method (for example, via a screen prompt). Your new module must still conform to the File Handling Redirector password module interface, that is:

Function Code | Action
= 1: | Register the supplied user-ID and password
= 0: | Return the user-ID and password. The File Handling Redirector module uses this call to obtain the user-ID and password when it is about to connect to the Fileshare Server.

Once you have written your own File Handling Redirector password module:

  • Windows: Create a cobfhrdrpwd.dll containing your module and ensure it is on the search path, PATH (you can do that by copying the file on the search path).
  • UNIX: Create a cobfhrdrpwd shared object containing your module and ensure it is on the search path, LD_LIBRARY_PATH (or SHLIB_PATH, or LIBPATH on different UNIX platforms).

You can create an object module and link it into any application executable as required.

Parent topic: Password System
Related information
Fileshare Client
Fileshare Server


Logon Validation Module

Introduction

If you have not activated the Fileshare Password System, the Fileshare Server validates requests to log on by calling the Fileshare Security Logon validation module (FSSecLog).

The FSSecLog module supplied with Fileshare allows any Fileshare Client to log on to a Fileshare Server. If you need to restrict the Fileshare Clients that can log on to a Fileshare Server, you must provide your own, alternative, FSSecLog module for the Fileshare Server to call.

For example, your own module can enable integration with the native operating system security, if this is needed.

The sequence of steps that your program and Fileshare follow is (see Figure 5-2):

  1. Your program registers a user-ID and password by calling the File Handling Redirector password module (FHRdrPwd)
  2. Your program performs the first I/O operation
  3. The File Handling Redirector module obtains the user-ID and password registered in step 1 by calling its password module (FHRdrPwd)
  4. The File Handling Redirector module passes the user-ID and password to the Fileshare Server
  5. The Fileshare Server calls the FSSecLog module passing the user-ID and password
  6. If the FSSecLog module allows logging on, a connection is established between the Fileshare Client and the Fileshare Server. If the FSSecLog module does not allow logging on, a status 9/037 "access denied" is returned to the Fileshare Client.

Logon Validation Module

Syntax:

call "fsseclog" using user-ID
                      password
                      return-status

Parameters:

user-ID | pic x(20).
password | pic x(20).
return-status | pic x comp-x.

On Entry:

user-ID | The Fileshare Client's user-ID
password | The Fileshare Client's password

On Exit:

user-ID | Unchanged
password | Unchanged
return-status | Set to 0 if the Fileshare Client is allowed to log onto the Fileshare Server. Any other status indicates the Fileshare Client is not allowed to log on and an error is returned to the Fileshare Client.

Comments:

Windows:

To use your own fsseclog module, create and link it into cobfssecurity.dll and place it on the search path, PATH. Fileshare will notify you that it has loaded the user security modules.

UNIX:

To use your own fsseclog module, create and link it into a cobfssecurity shared object and place it on the search path, LD_LIBRARY_PATH (or SHLIB_PATH, or LIBPATH on different UNIX platforms). Fileshare will notify you that it has loaded the user security modules.

Parent topic: Security
Related information
Password System
File Access Validation Module
Password File Maintenance
User-ID Groups
Supervisor Mode


File Access Validation Module

Whenever a Fileshare Server receives an open request on a file from a Fileshare Client, the Fileshare Server calls the Fileshare Security at Open validation module (FSSecOpn).

The Fileshare Security at Open Validation module supplied with Fileshare allows any Fileshare Client to access a data file. If you need to restrict access to specific files, you must provide your own, alternative, Fileshare Security at Open Validation module for the Fileshare Server to call.

If the Fileshare Security at Open Validation module allows the file access, the operation is allowed to complete. If the module does not allow the file access, a file status of 9/037 "access denied" is returned to the Fileshare Client and the operation is not allowed to complete.

Note: This file access security check is entirely independent of the Fileshare Password System and the User Supplied Logon Validation Module.

The sequence of steps that your program and Fileshare follow are:

  1. Your program registers its user-ID and password with the File Handling Redirector password module. This information is used when the Fileshare Client first logs onto the Fileshare Server.
  2. When your program subsequently performs an I/O operation on a file that it does not have open (such as an Open or Delete file operation), the Fileshare Server calls the Fileshare Security at Open Validation module (FSSecOpn)

You can replace the supplied Fileshare Security at Open Validation module with one of your own in order to use your own criteria for validating the open request. Your new module must comply with the Fileshare Security at Open Validation module's interface described below

Syntax:

call "fssecopn" using filename
                      filename-length
                      operation-code
                      user-ID
                      return-status

Parameters:

filename | pic x(n).
filename-length | pic x(2) comp-x.
operation-code | pic x(2) comp-x.
user-ID | pic x(20).
return-status | pic x comp-x.

On Entry:

filename | The name of the data file that the Fileshare Client wants to open
filename-length | The length of filename
operation-code | The operation code specifying the I/O operation. These codes are those used by the Callable File Handler. See your online help for details on the Callable File Handler.
user-ID | The user-ID of the Fileshare Client making the open request

On Exit:

return-status Set to 0 if the open request is allowed. Any other status indicates that the Fileshare Client is not allowed to open the data file and an error status is returned.

Comments:

Windows:

You can create your own fssecopn module, link it into the cobfssecurity.dll and place it on the search path, PATH. Fileshare will notify you that it has loaded the user security modules.

UNIX:

You can create your own fssecopn module, link it into a cobfssecurity shared object and place it on the search path, LD_LIBRARY_PATH (or SHLIB_PATH, or LIBPATH on different UNIX platforms). Fileshare will notify you that it has loaded the user security modules.

Parent topic: Security
Related information
Password System
Logon Validation Module
Password File Maintenance
User-ID Groups
Supervisor Mode


Password File Maintenance

The password file contains details of user-IDs and passwords that the Fileshare Server uses when Fileshare Password Security is enabled. Because the information in the password file is encrypted for security reasons, you can only add records to and remove records from the password file using the Password File Maintenance Utility.

UNIX:
Note:
  • In this section, options are shown starting with a forward slash (/). This is how you specify the options on Windows. On UNIX, use the hyphen (-) character instead of the forward slash.
  • Filenames are shown using the Windows naming convention. On UNIX, use the UNIX filenaming conventions.

Use the /pf (password file) option to add or remove entries in the password file, for example:

fs /pf pass.dat [options]

This invokes password file maintenance and appends the specified options to the password file pass.dat. If this file does not exist, it is created.

The following options are available:

  • /u user-ID
    /pw password

    These add the specified user-ID and password to the password file. Both user-ID and password are case-sensitive and can be up to 20 characters in length.

  • [/e]

    This erases the record from the password file and is the only way to remove a record once the password file has been created.

Example

fs /pf pass.dat /u pkel /pw fishwife

This example invokes password file maintenance, creates or updates a password file called pass.dat and adds a user-ID of pkel and password of fishwife.

Parent topic: Security
Related information
Password System
Logon Validation Module
File Access Validation Module
User-ID Groups
Supervisor Mode


User-ID Groups

You can group user-IDs by using the # character. If the # character is present in a user-ID, Fileshare registers the full passed user-ID but only performs logon validation on the portion of the user-ID prior to the # character.

When adding entries to the password file, you should create them as exclusive up to the # character. See the section Password File Maintenance for further information.

If you use view a user with a utility such as FSVIEW, the user information returned will show the full user-ID supplied by the client. Note that any reference to a user must be made using the full user-ID.

Example

fs /pf pass.dat /u pkel#1 /pw fishwife

This example invokes password file maintenance, creates or updates a password file called pass.dat and adds a user-ID of pkel#1 and password of fishwife.

Parent topic: Security
Related information
Password System
Logon Validation Module
File Access Validation Module
Password File Maintenance
Supervisor Mode
Password File Maintenance


Supervisor Mode

In order to use the password-restricted functions of Fileshare Manager, a supervisor password must be defined (see the section Fileshare Manager in the chapter Advanced Operation).

To define a supervisor password, an entry must be made in the password file using the reserved user-ID, FSVIEW. Note that the user-ID FSVIEW must be entered in upper case.

If you are already using Fileshare Password Security, simply add the FSVIEW entry to your existing file.

If you are not using Fileshare Password Security, you can create a password file that contains a single entry, the FSVIEW user-ID. This defines a supervisor password without enabling Fileshare Password Security.

Example

The following example defines a supervisor password of "abracadabra" in the password file password.fil. If the file does not exist, it is created.

fs /pf password.fil /u FSVIEW /pw abracadabra

Once you have defined a supervisor password, you must specify the password file, either in the Fileshare Server configuration file, or on the command line when the Fileshare Server is started.

Note:

If FSVIEW is the only entry in the password file, the Fileshare Server displays a message indicating that Fileshare Password Security is disabled, even though a password file has been specified.

Parent topic: Security
Related information
Password System
Logon Validation Module
File Access Validation Module
Password File Maintenance
User-ID Groups
Fileshare Manager


Advanced Operation

  • Single User Mode
  • Filename Mapping
  • Data and Key Compression
  • Virtual File Handler Interface
  • Monitoring Fileshare
  • Fileshare Manager
  • Fileshare Manager Configuration
  • Linking Fileshare Manager Applications
  • Byte-stream I/O Calls
  • Fileshare Server Configuration
  • Performance Considerations
  • Large File Support with Fileshare
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Fileshare on UNIX
Error Handling
Fileshare Server Messages


Single User Mode

You can configure Fileshare to run in single user mode. All network communication is bypassed and the Fileshare Client makes direct calls to the Fileshare Server module. The Fileshare Server does not run as a separate process in this mode of operation.

This is useful when:

  • You want to develop Fileshare applications without using a network or multiple sessions
  • A single-user application makes use of one of Fileshare's advanced features, such as transaction processing

To run Fileshare in single user mode, set the FSCOMMS environment variable to $local, for example:

Windows:

set FSCOMMS=$local /s servername

UNIX:

set FSCOMMS="\$local" /s servername
export FSCOMMS

Even when you are running in single user mode, you must still inform the Fileshare Client which Fileshare Server to use, either by specifying the Fileshare Server name as part of the filename in your program or by using a Fileshare Client configuration file.

The Fileshare Server is configured in the normal way using a Fileshare Server configuration file. At the minimum, you must define a Fileshare Server name in this file.

Note:

The Fileshare Server does not have control over the screen when it is running in single user mode. It directs all screen output to the file fsscreen.lst in the current Fileshare Client directory. If your program fails, check this file for messages.

The FSSERVER environment variable must be unset.

Parent topic: Advanced Operation
Related information
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


Filename Mapping

Filename mapping enables I/O requests made against one data file to be mapped to a different data file when your program is executed. For example, you can use filename mapping to enable applications that use DOS file naming conventions to access data files under the control of a Fileshare Server running on an operating system that uses different file naming conventions, such as UNIX or NetWare.

You do not need to change the configuration of the Fileshare Client to use filename mapping.

  • Fileshare Server
Parent topic: Advanced Operation
Related information
Single User Mode
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


Fileshare Server

To enable filename mapping, use the /af (alternate filename) option with the /f option in the database reference file.

The /fs (filename string) option used in conjunction with the /af option enables you to substitute characters at the start of a filename. This is particularly useful for mapping pathnames.

For example:

fs /d dbase.ref /f old.dat /af new.dat
fs /d dbase.ref /fs c: /af e:

adds entries to the database reference file dbase.ref which specify that:

  • All requests to the data file old.dat are redirected to the data file new.dat
  • All accesses to data files starting with c: are directed to drive e:

If the Fileshare Server finds an entry specifying an alternate filename, any character string substitution specified by a /fs option is applied to the new filename.

After processing any string substitution specified by an /fs option, the Fileshare Server does not search the database reference file for any matching /f option using the new filename.

Fileshare processes all filenames as relative to the Fileshare Server's current directory if you have not given a fully qualified filename after the /f option or a fully qualified filename is not passed from the Fileshare Client.

All filenames and paths are forced to upper case by Fileshare Servers not running on the UNIX operating system and are expanded to include the full path to ensure matching. Filenames specified with the /af option are not modified.

Example 1:

fs /d dbase.ref /f file1.dat /af c:\data\file2.dat

This example adds entries to the database reference file dbase.ref that specify that file accesses to the file file1.dat are mapped to the alternate filename file2.dat.

Example 2:

fs /d dbase.ref /f file1.dat /af c:\data\file2.dat
fs /d dbase.ref /fs c: /af e:

This example adds entries to the database reference file dbase.ref that specify that all requests made to the data file file1.dat are redirected to the alternate filename and, in addition, the alternate filename is changed, using string substitution, to be on drive e:.

Parent topic: Filename Mapping


Data and Key Compression

You can configure the Fileshare Server so that data files are created using data or key compression.

You do not need to change the Fileshare Client configuration in order to use data or key compression on a data file.

  • Data and Key Compression - Fileshare Server
Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


Data and Key Compression - Fileshare Server

To enable data or key compression for a data file, use the /k option in the database reference file. In conjunction with the /k option, use the d option to specify data compression and the i option to specify key compression.

Values that you specify after the d and i options are the same values that you would specify using the Compiler directives DATACOMPRESS and KEYCOMPRESS.

Data and key compression specifications in the database reference file are effective only if the Fileshare Server creates the data files. They do not affect existing data files. For existing files, the data and key compression information is retrieved from the data file header. Any settings in your program or the database reference file are ignored.

Example:

fs /d dbase.ref /f file1.dat /k d001
fs /d dbase.ref /f file2.dat /k d001i7

This example tells the Fileshare Server to create the file file1.dat with data compression and the file file2.dat with both data and key compression.

Parent topic: Data and Key Compression


Virtual File Handler Interface

The Fileshare Server can pass I/O requests to a program specified by you, rather than by the Micro Focus File Handler, as long as the program that you specify conforms to the call interface used by the File Handler.
Note: If you are handling files using DXFORMATs 17 and 21, transaction processing capabilities are not supported.

You do not need to change the configuration of the Fileshare Client to use the Virtual File Handler Interface.

  • Fileshare Server
Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


Fileshare Server

To specify a virtual file handler, use the /ap (application program) option with the /f option in the database reference file to specify the program to which I/O requests for a particular data file are passed by the Fileshare Server.

Example:

fs /d dbase.ref /f user1.dat /ap myprog

This adds entries to the database reference file, dbase.ref which specify that the Fileshare Server should pass all I/O requests for the data file user1.dat to the program myprog.

Windows:

UNIX:

On UNIX, your program should be compiled to intermediate or generated code, or to a callable shared object, and must be callable from the Fileshare process.

You also need to use the fcd3 copybook instead of the standard fcd layout.

Parent topic: Virtual File Handler Interface


Monitoring Fileshare

When the Fileshare Server is active, you can toggle the trace option on and off using the F2 key. If the trace option is on, the Fileshare Server displays the file access requests on the console as they happen. Each line of trace provides:

  • Input:
    • The user-ID assigned, in the order that the Fileshare Clients logged onto the Fileshare Server
    • The operation code, indicating the I/O operation requested (see the online help on the Micro Focus File Handler for further information about operation codes)
    • The name of the file being accessed
  • Output:
    • The status returned to the Fileshare Client, indicating the result of the operation
Note:

The trace option can degrade performance. You should only use it as a diagnostic aid in problem investigation.

You can activate the trace option when the Fileshare Server is started using the "/tr f" option. This causes the trace to be written to the file fsscreen.lst, as well as being displayed on the screen. Note, however, that this severely impacts the Fileshare Server performance if tracing is switched on. If, however, tracing is switched off, only information messages are written to the screen and to the file. This is a useful method of keeping a permanent record of Fileshare messages on disk.

If you are using Fileshare in single user mode (see the section Single User Mode), the trace display, together with all other output normally displayed on the Fileshare Server console screen, is written to the file fsscreen.lst in the Fileshare Server's current directory .

Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare
Single User Mode


Fileshare Manager

You can use the Fileshare Manager (fsmgr) to automate some of Fileshare's supervisor mode functions by writing a COBOL program to call it. The Fileshare Manager can be called to instruct a Fileshare server to:

  • Perform an automatic backup of its recovery log file
  • Close all of its currently open data files. Any client application accessing these files is returned a file status, indicating that the file is no longer open. This is particularly useful in the event of a system crash or power failure, either of which could cause a Fileshare client program to terminate without disconnecting properly from Fileshare. If this happens, and data files are left open on the Fileshare server, it can prevent automatic disk backups from running and possibly prevent other clients from accessing the files.
  • Log off any clients currently connected to it, close any open files and roll back any incomplete transactions belonging to these clients.Any subsequent access attempts by these client applications result in an error status (9/125).
  • Close down completely. Any open files are closed and any incomplete transactions rolled back
  • Close down completely and then re-start. If a backup directory has been specified in the database reference file, Fileshare copies all the files named in the database reference file to the backup directory, deletes the recovery log file(s) and re-starts with a new recovery log file.
Note: Any Fileshare Clients connected to the Fileshare Server when this instruction is issued will be logged off and any files which they had open will be closed.

The Fileshare Manager program (fsmgr) is called from a COBOL program as follows:

Syntax:

call "fsmgr" using parameter-block

Parameters:

parameter-block
A group item defined as:
function-code
pic xx comp-x.
error-status
pic xx comp-x.
fileshare-name
pic x(16).
supervisor-passwd
pic x(20).
reserved
pic x(24).

On Entry:

function-code
The Fileshare Manager program function required:
1 | Backup recovery log file
2 | Close all open data files
3 | Log off all connected clients
4 | Shut down Fileshare
5 | Shut down and re-start Fileshare
fileshare-name
The name of the Fileshare server (this is the name that was used when Fileshare was started)
supervisor-passwd
The supervisor password. See the section Supervisor Mode in the chapter Security for more information
reserved
Reserved for future use. Must contain binary zeros.

On Exit:

error-status
Reflects the success, or failure, of the call. Possible values of error-status are shown below.
Value | Meaning
0 | Function completed successfully
1 Communications error. A Fileshare server of the name specified in fileshare-name could not be contacted on the network using the specified communications protocol. This error is also returned if a network failure occurs during the execution of the function but after the initial connection was made.

Check that fileshare-name is specified correctly and that the Fileshare Handling Redirection module (FHRedir) is configured to use the correct communications protocol.

2 File error during initial connection.

To connect to Fileshare, the Fileshare Manager opens a file called fsmgr.ctl. This file should not already exist and the Fileshare Manager does not actually create it. If it does exist, this status is returned if there is a subsequent error in closing the file.

3 Invalid password specified in supervisor-password.

Ensure that Fileshare is running with a password file and that the contents of supervisor-password match the supervisor password entry in the password file. Note that Fileshare passwords are case sensitive.

See Supervisor Mode in the chapter Security for more information.

4 | Invalid value specified in function-code - must be within the range one to five
5 No Fileshare log file.

You have attempted to backup the log file on a Fileshare server that is running without a recovery log file.

6 Function 2 or 3 could not complete.

While attempting to log off all Fileshare's clients (function 3), it is possible for other clients to log on before the logging off operation completes. For example, the Fileshare Manager has to send a "logoff client n" request four times if there are four clients logged on. If, however, a new client logs on before all four original clients have been logged off, the Fileshare Manager retries the "logoff client n" request in order to log off the new client. It retries 10 times and if new clients are still logging on, it returns error 6. A similar situation can occur during processing of a function 2 (close all data files) if new files are continuously being opened at the same time.

10 | Other error
Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare
Supervisor Mode


Fileshare Manager Configuration

Fileshare Manager, like other Fileshare Client applications, accesses a Fileshare server via the Fileshare Handling Redirection module (FHRedir) and so needs to be configured to use the correct communications protocol. See the section Client Configuration in the chapter Configuration for more information.

Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare
Client Configuration


Linking Fileshare Manager Applications

On Windows, if your program calls the Fileshare Manager, you need to link in the Fileshare manager object file (fsmgr.obj when you create an executable file.

Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


Byte-stream I/O Calls

Fileshare supports some of the byte-stream I/O routines that are available with this COBOL system. Most of the routines use the same parameters and have the same effect as the corresponding COBOL system call, but access remote files via Fileshare. The only change needed to your program is to call the routine starting with FS_ instead of CBL_. The only routine that does not have exactly the same call interface as its corresponding CBL_ routine is FS_LOCATE_FILE.

Fileshare supports the following byte-stream I/O routines:

  • FS_CHECK_FILE_EXIST
  • FS_CLOSE_FILE
  • FS_CREATE_FILE
  • FS_COPY_FILE
  • FS_DELETE_FILE
  • FS_JOIN_FILENAME (see below)
  • FS_LOCATE_FILE (see below)
  • FS_OPEN_FILE
  • FS_READ_FILE
  • FS_RENAME_FILE
  • FS_SPLIT_FILENAME (see below)
  • FS_WRITE_FILE

You can use these routines to access files on remote Fileshare servers, as well as local files. Configure the Fileshare Client in the normal manner to define which files are local and which are remote.

Note:

  • The FS_COPY_FILE routine only works on the Fileshare server and cannot be used to copy the file locally or to another Fileshare server. Currently you would have to code your own FS_OPEN_FILE and FS_READ_FILE/CBL_WRITE_FILE loop to copy the contents of the file locally.
  • Do not use byte-stream I/O and COBOL I/O on the same file
  • If you want to share files between multiple Fileshare Clients you must access the files using normal COBOL I/O verbs
  • FS_LOCATE_FILE
  • FS_SPLIT_FILENAME and FS_JOIN_FILENAME
Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare


FS_LOCATE_FILE

The functionality provided by FS_LOCATE_FILE is the same as CBL_LOCATE_FILE except:

  • You cannot use FS_LOCATE_FILE to search for files in libraries on remote Fileshare Servers
  • You can use CBL_LOCATE_FILE to search for files along each path specified in an environment variable. You can then use the returned actual-file-spec as the filename when opening the file.

    If you have specified a $$server-name prefix in user-file-spec, actual-file-spec must contain the same $$server-name prefix for an OPEN using actual-file-spec to be re-directed automatically. By default, Fileshare only returns the filename in actual-file-spec to your program. To return the $$server-name in actual-file-spec, set the most significant bit of user-mode before making the call to FS_LOCATE_FILE.

  • When a remote file is found, using an environment variable containing many paths, FS_LOCATE_FILE returns actual-file-spec including the full path where the file is located

When a call to FS_LOCATE_FILE is directed to a custom file handler by configurable DYNREDIR, the customer file handler is called with op-code FAF8 plus fcd(3:1) and uses the value 5 to specifiy it as an FS_LOCATE_FILE call.

On Entry Fields

On entry, the following fields are set:

fcd-name-ptr | Pointer to the user file
fcd-open-mode | User mode
fcd-optional | Path flag
fcd-name-length | Length of filename

On entry, the length of the fcd-name-length field is the same as the length of the filename pointed to by the field fcd-name-ptr.

On exit, you need to set the following fields:

fcd-record-ptr | Pointer to the actual file spec
fcd-access-mode | Exist flag
fcd-file-status | File status
Parent topic: Byte-stream I/O Calls
Related information
FS_SPLIT_FILENAME and FS_JOIN_FILENAME


FS_SPLIT_FILENAME and FS_JOIN_FILENAME

The functionality provided by FS_SPLIT_FILENAME and FS_JOIN_FILENAME is the same as that provided by the corresponding CBL_routines. In addition, using FS_SPLIT_FILENAME and FS_JOIN_FILENAME you can process filenames that specify Fileshare Server names using the $$server-name prefix at the front of the filename. When processing such filenames, the $$server-name prefix characters are included as part of the pathname parameter.

If you have included the callable sort, and receive error 173 after switching to release build, you need to include fhrsub.obj in your project.

Parent topic: Byte-stream I/O Calls
Related information
FS_LOCATE_FILE


Fileshare Server Configuration

Windows:

When the Fileshare Server service starts, it is configured according to the Fileshare Server configuration file. By default, the service takes its configuration from %windir%\system32\fs.cfg, where %windir% is for example c:\winnt\system32. You can edit this file or create your own here or elsewhere.

The /cf option enables you to specify a configuration file containing the configuration options. For example, the following command installs a service called "Micro Focus Fileshare Service: My Service", which takes its configuration from the file c:\mydir\myfs.cfg:

    fsservice -i "My Service" c:\mydir\myfs.cfg

To use a different working directory, specify this using the /wd option as the first entry in your configuration file. On start-up, Fileshare changes to your specified working directory and accesses any files that are not fully qualified as being relative to this working directory. For example, the following command installs a service called "Micro Focus Fileshare Service: My Service", which will execute in the c:\mydir directory:

    fsservice -i "My Service" /wd c:\mydir /cf c:\mydir\myfs.cfg

Because Fileshare runs as a background process, any messages it generates are written to the file fsscreen.lst in the current working directory. Check the contents of this file to diagnose any problems.

Example:

The following is an example of a Fileshare Server configuration file:

    /wd d:\fsdir
    /s server1
    /d dbase.ref

where:

  • /wd d:\fsdir specifies the directory fsdir on the drive d: as the Fileshare Server's current directory. Any data files without fully qualified pathnames are searched for relative to this directory.
  • /s server1 specifies that the Fileshare Server is to register its name on the network as server1
  • /d dbase.ref specifies that Fileshare is to use the database reference file dbase.ref. Because this name is not fully qualified it is searched for in Fileshare's current directory, that is, d:\fsdir.

For details on the configuration options, see the section Server Configuration in the chapter Configuration.

Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Performance Considerations
Large File Support with Fileshare


Performance Considerations

Although Fileshare reduces the number of requests made across the network for COBOL I/O, some types of data file access benefit more than others. The following areas affect Fileshare's ability to improve the speed of accessing remote data:

  • File organization

    A single request to an indexed data file can involve many accesses to the physical data file itself such as reading the header and updating the integrity marker. Complex key structures also increase the number of accesses needed to update the index structure in the file. Using the normal COBOL file handling system, each of these accesses generates a request that is sent across the network. Using Fileshare, only one request is sent across the network. The simpler data file organizations (relative and sequential files) involve a smaller processing overhead.

    Any speed improvements using Fileshare are therefore more apparent when processing indexed data files.

  • I/O request

    The number of accesses to a data file needed to process a WRITE, DELETE or REWRITE operation is generally larger than the number needed to process a READ or START operation. Using the normal COBOL file handling system, each of these accesses generates a request that is sent across the network. Using Fileshare, only one request is sent across the network.

    Any speed improvements using Fileshare are therefore more apparent when performing WRITE, DELETE or REWRITE operations.

  • Concurrent use of data files

    If your program opens a data file exclusively, the normal COBOL file handling system uses caching. This means that it does not have to check to see if the file has been updated on every I/O operation. The number of requests sent across the network, therefore, is significantly less if the data file is opened exclusively.

    Fileshare provides a greater improvement in performance, therefore, when a large number of users require concurrent access to data files than when files are opened exclusively. This is because access and caching are controlled by the Fileshare Server and so the additional requests needed when accessing a shared data file via the normal COBOL file handling system are not needed.

Any speed improvements are therefore very specific to individual applications and become more pronounced as more Fileshare Clients concurrently access the same data files.

We recommend you always use the synchronous mode of operation for best performance with Fileshare. Async-mode should be considered as being for development purposes only, and production installations should always use synchronous operation.

UNIX:

On UNIX, when running the Fileshare Server and Fileshare Client on the same machine, we recommend that you use the CCINAMPU CCI protocol as it performs better in this situation than the CCITCP protocol.

  • Fileshare Performance on UNIX
Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
Large File Support with Fileshare


Fileshare Performance on UNIX

UNIX:

Fileshare improves performance when remote COBOL applications are concurrently accessing shared data files across a network but it cannot improve peformance when the COBOL data resides on the same machine as the application. In this configuration, there is actually a performance overhead when using Fileshare instead of the standard Callable File Handler.

Although UNIX machines can be used as remote data servers, it is not uncommon for the application itself to run on the machine where the data resides. For example, multiple users may log in, across a network, to a machine where they run applications which share the same data. In such a configuration, you encounter the performance overhead of using Fileshare, making performance slower than when using the standard Callable File Handler.

Parent topic: Performance Considerations


Large File Support with Fileshare

Fileshare, by default, supports files that can be up to 32 Terabytes in size.

An alternative technology, file striping, was introduced in previous releases as an interim solution to overcome limitations on the maximum allowed file size some operating systems permit. It enables you to specify that a single data file is to be stored in multiple physical files (or stripes) on disk.

Because of the complications involved with configuring striping together with Fileshare (these issues are discussed below), we recommend that you keep your large files non-striped and instead, configure the file handler to use its standard large file support.

To configure large file support under Fileshare, you should consider the following:

  • Location of the extfh.cfg file

    The extfh.cfg file must be located in the same directory as the Fileshare Server or, if the EXTFH environment variable has been set to point to the extfh.cfg file, it must have been set in the Fileshare Server session.

  • Switching on large file support

    Makes sure the value of FILEMAXSIZE specified in the extfh.cfg file is 8. This is the default value.

The following information explains how to configure striped files under Fileshare control if your operating system does not support large files:

  • Expanded filenames in the extfh.cfg file

    You must use the fully qualified name of the base file in the extfh.cfg configuration file. This name includes the pathnames that you can see if you press F2 at the Fileshare Server to switch tracing on.

    UNIX:

    For example, on UNIX:

    [/u/username/file.dat]
Striping=on
    Note:

    You need only do this for files accessed through Fileshare. To enable the file handler to find the setting in extfh.cfg the filename tag must match exactly that specified by the I/O request, which in the case of Fileshare includes a fully qualified path.

  • Backslash character

    The backslash character is treated as an escape character within the extfh.cfg file.

    Windows:

    On Windows platforms you must therefore specify two backslash characters for each backslash character in the pathname, for example:

    [d:\\fsrvr\\file.dat]
Striping=on
  • Alternate filenames

    You can specify file striping on an alternate filename (specified in the database reference file using filename mapping). In this case, the expanded filename is not required. For example, if the database reference file contains the following line:

    /f file1.dat /af file2.dat

    you can specify the following in the extfh.cfg file:

    [file2.dat]
Striping=on
  • StripeNameType

    StripeNameType=1 (the default is StripeNameType=0) only works with Fileshare if the base filename does not have an extension. If you specify StripeNameType=1 for a filename that has an extension, the file is created but it is not striped.

  • Back up and recovery

    The use of striping complicates the process of logging for rollforward recovery because the administrator has to ensure that the correct versions of the files are in the latest backup, and that they are correctly restored in the event of needing to run the Fileshare Recovery Utility. This process is much more complex if file stripes also have to be maintained.

    The Automatic Database Backup and Recovery facility does not work correctly on striped files because it uses low-level I/O routines for backups and restores which are unaware of the stripe configuration.

  • Not using Fileshare

    The filenames passed to the File Handler must match exactly so that the File Handler can locate the filename tags in the extfh.cfg file.

    Generally, only Fileshare passes fully qualified names. Therefore, if you have set up an extfh.cfg file for use under Fileshare with expanded pathnames and then want to access the files outside of Fileshare, you need to change the filename tags in extfh.cfg to match exactly the filenames passed by the application.

Parent topic: Advanced Operation
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager
Fileshare Manager Configuration
Linking Fileshare Manager Applications
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations


Fileshare on UNIX

  • Running Fileshare as a Background Process
  • The NFILES Setting
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Error Handling
Fileshare Server Messages


Running Fileshare as a Background Process

The Fileshare Server uses the Enhanced Accept/Display syntax (Adis module) for its screen displays and keyboard handling. Consequently, the Fileshare Server uses much more processor time if you start it as a background UNIX process. To avoid this overhead, you should configure the Fileshare Server using the -b option. This disables all Fileshare displays and keyboard reading.

Since Fileshare does not read the keyboard in background mode, you cannot close it down in the normal manner using the Esc key sequence.

CAUTION:

Do not kill the Fileshare process because this results in the corruption of any data files which are open.

Instead, write a program which calls Fileshare Manager. Alternatively, you can run the supplied utility cobfsclose as follows:

cobfsclose

The cobfsclose utility calls Fileshare Manager itself and prompts you for the name of the Fileshare Server you want to close down and the CCI protocol.

Because you can only shut down the Fileshare Server remotely, the Fileshare Server must have been configured to use a password file. See the section Password File Maintenance in the chapter Security for details.

The Fileshare Server does not start in background mode unless you start it with a password file.

In background mode, any messages the Fileshare Server would normally display on the screen are written to the file fsscreen.lst in the Fileshare Server's current directory.

An example configuration file follows.

-s server-1
-pf password.fil
-cm ccitcp

This configuration file specifies:

  • Fileshare Server name is server-1
  • Password file is password.fil
  • Communications protocol to use is CCITCP
  • -b option invokes running in background mode

On UNIX, you can now start the Fileshare Server in background mode by entering:

fs -b > server-1.log 2>&1 &

On some UNIX systems, output can be sent to the terminal after it has been disconnected. When this happens the entire session terminates. Consequently, you need to redirect the output from the command.

Parent topic: Fileshare on UNIX
Related information
The NFILES Setting
Password File Maintenance


The NFILES Setting

On UNIX systems, the NFILES setting defines how many separate file descriptors can be used in the File Handler config file. This can be set for individual accounts and for the system as a whole. You must ensure that the number of separate file descriptors is set sufficiently high for Fileshare which uses them as follows:

  • One file descriptor is used for every file opened on disk. So, two file descriptors are used for each indexed file opened. Note that two users sharing the same file only require the file to be opened once on disk.
  • CCITCP uses one file descriptor for every connected Fileshare client
  • CCITCP uses one file descriptor for every outstanding Fileshare request (normally this is a maximum of two)

For the user account that the Fileshare session uses, NFILES must be set to accommodate the maximum number of open files and the maximum number of Fileshare clients. In addition, the system setting of NFILES may need to be increased.

Parent topic: Fileshare on UNIX
Related information
Running Fileshare as a Background Process


Error Handling

This chapter details:
  • Fileshare-specific causes of run-time status codes returned by the COBOL system
  • Communications errors generated by CCI
  • Transaction processing errors
  • COBOL Run-time Errors
  • Communications Errors
  • Transaction Processing Errors
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Fileshare Server Messages
Fileshare Server Messages


COBOL Run-time Errors

Status Code | Meaning
9/037 Access is denied. In addition to the normal situations where this error occurs, Fileshare generates this error when:
  • An invalid user-ID and/or password is passed to a Fileshare Server and Fileshare Password Security is active
  • A Fileshare Client attempts to access a particular data file and access is denied

See the chapter Security for more information.
9/100 | A CLOSE operation is tried on a data file that is participating in an active transaction. See the section Transaction Processing in the chapter Database Integrity for more information.
9/124 | A communications error occurred between the Fileshare Client and the Fileshare Server. You can call fs_status to determine the cause of the error. For details of this call see the section Communications Errors.
9/125 Caused by one of these conditions:
  • A transaction or record lock timed out. (See the section Automatic Record Lock Timeout in the chapter Database Integrity.)
  • The Fileshare Client has been forced to log off from the Fileshare Server
  • If you are using the Micro Focus File Handler interface, an invalid Fileshare session ID was passed on the call to the File Handling Redirector module. Check that the six bytes of the FCD from offset 79 have not been changed.
  • A previous access to this open file returned a 9/124 status, so further operations cannot be made
9/126 | The record size used on the I/O operation is too large to be handled by the Fileshare Server. See the description of the /m option in the section Server Configuration in the chapter Configuration.
9/173 | When using the virtual file interface, the program-name specified in the database reference file is not found. See the section Virtual File Handler Interface in the chapter Advanced Operation.
Parent topic: Error Handling
Related information
Communications Errors
Transaction Processing Errors
Security
Transaction Processing
Communications Errors
Automatic Record Lock Timeout
Server Configuration
Virtual File Handler Interface


Communications Errors

Error status 9/124 on an I/O operation indicates that a communications error has occurred between the Fileshare Client and the Fileshare Server.

The most common time for error 9/124 to occur is on the very first I/O request that your program makes. It is then that the Fileshare Client tries to contact the Fileshare Server. If the Fileshare Client is unable to do this, it returns error 9/124. If you receive this error, examine the configuration of Fileshare and check that:

  • The Fileshare Server is started and operational
  • You have specified the correct Fileshare Server name. The name that you specify must exactly match the name specified when the Fileshare Server was started.
  • The Fileshare Client and Fileshare Server are configured to use the same CCI communications protocol
  • You have a working network connection between the Fileshare Client and the Fileshare Server and the correct network driver and software is loaded

Once you have made a successful connection and the Fileshare Server is servicing the request from the Fileshare Client, the request is visible if trace is active at the Fileshare Server. See the section Monitoring Fileshare in the chapter Advanced Operation for more information. Any further communications errors are returned to the program using the error code 9/124. This is a fatal error and the Fileshare Client drops the connection to the Server. To determine the cause of the error, call the entry point fs_status in the the File Handling Redirector module. The format of the call is:

call "fs_status" returning cci-status

where the parameter is defined as:

01 cci-status   pic x(2) comp-x.

On return, cci-status contains the CCI error code returned to the File Handling Redirector module from the CCI module. For details of CCI error codes, please refer to your book, Configuring CCI.

You can make an additional call after error 9/124 to obtain an extended error message. This message is in the form of a text string that indicates a CCI-specific error as well as some additional information. The format of the call is:

call "fs_commserr" using by reference buffer
                         by value maxlen
                         by reference actual-len

where the parameters are defined as:

01 buffer       pic x(n).
01 maxlen       pic x(4) comp-5 value length of buffer.
01 actual-len   pic x(4) comp-5.

On return, buffer contains the extended error message and actual-len contains the length of this message. The additional information in the returned message includes:

  • The date and time that the last error 9/124 was returned
  • Last return code from the CCI module (a 4-digit number)
  • Message code (for the File Handling Redirector module's internal use, a 2-digit number)
  • The CCI error message text

In addition, the File Handling Redirector module automatically logs communications errors in a local file called fhneterr.log. Each entry in the log file has the same format as the buffer returned from the fs_commserr call.

If you do not have a call to fs_commserr in your application, you can check this file for more detailed information following a 9/124 error.

This log file is not deleted by the Fileshare Client. You can, however, delete it if its contents are of no interest.

Parent topic: Error Handling
Related information
COBOL Run-time Errors
Transaction Processing Errors
Monitoring Fileshare


Transaction Processing Errors

The COMMIT and ROLLBACK operations work across many data files. You cannot check the file status of any one data file to see if the COMMIT or ROLLBACK operation was successful. Instead, call the entry point fs_status to determine the status of the COMMIT or ROLLBACK operation.

The format of the call is:

call "fs_status" returning t-status

where the parameter is defined as:

01 t-status   pic x(2) comp-x.

A non-zero status indicates that the COMMIT or ROLLBACK operation failed. Fileshare cannot provide definitive information on transaction processing errors because of the complexity of multiple file transactions across networks.

Parent topic: Error Handling
Related information
COBOL Run-time Errors
Communications Errors


Fileshare Server Messages

These are of varying levels of severity:

  • Severe

    Severe level messages indicate that a problem has occurred that has prevented the Fileshare Server carrying out the requested operation. The cause of the error should be rectified and then the operation tried again.

  • Warning

    Warning level messages indicate that a situation was encountered that the Fileshare Server was not expecting, but was able to continue.

  • Informational

    Informational level messages provide information about the operations that the Fileshare Server is performing.

The format of each message is as follows:

FSnnn-x text

where:

Parameter | Description
FS | Fileshare Server message
nnn | Message number
x | Indicates the severity of the message ("S", "W" or "I")
text | Text of the message

For more information on the messages, see the links below.

  • Messages from FS001-S to FS050-W
  • Messages from FS051-W to FS099-W
  • Messages from FS101-I to FS149-I
  • Messages from FS151-I to FS200-W
  • Messages from FS201-S to FS252-S
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Fileshare on UNIX
Error Handling


Messages from FS001-S to FS050-W

  • FS001-S The parameter "text " is not recognized as a valid parameter.
    This error status is displayed when the Fileshare Server parses the specified parameters and finds one which it does not recognize.
  • FS004-S The parameter "text " specifies a time-out value that is invalid.
    The /t parameter has been specified in a configuration file, but the characters following do not conform to a valid specification of a time-out value.
  • FS005-S The parameter "text " is too long or invalid.
    The parameter indicated could not be processed correctly. This can be for one of the following reasons:
  • FS006-S The parameter "text " has already been specified.
    A duplicate parameter has been specified and duplicates are not permitted for this parameter.
  • FS007-S Invalid parameter combination.
    Fileshare has processed the specified parameters and is unable to process the information given.
  • FS008-S Communications Initialization Failure.
    An error has occurred when the Fileshare Server initialized CCI or the Fileshare Server was unable to perform the CCI call because the required operating system and/or Micro Focus communication support modules are not available. This error can also indicate a problem with the network setup on the machine (for example, the required drivers have not been loaded).
  • FS009-S The required communications module cannot be found.
    The Fileshare Server tried to load the CCI module required for the protocol specified, but was unable to do so. This implies that the CCI module (or required support modules) cannot be found or they cannot be loaded.
  • FS011-W Communications send failure.
    The Fileshare Server encountered a communications error when it tried to return the result of an I-O operation to a Fileshare Client. This can imply that there is a problem with the network or that the Fileshare Client process terminated abnormally.
  • FS012-W Communications disconnect failure.
    The Fileshare Server tried to drop the connection with the Fileshare Client, but the communications system returned an error. The Fileshare Server tries to disconnect from Fileshare Clients when:
  • FS013-W Communications receive error.
    An unexpected error occurred while receiving information from the communications system. This error implies a problem with the network software or hardware because a message has been received but could not be processed correctly.
  • FS014-W Communications data length not as expected.
    The information sent from the Fileshare Client to the Fileshare Server includes a check on the amount of information that is being sent. This error occurs when the amount of data received by the Fileshare Server is not the same as the amount sent by the Fileshare Client.
  • FS015-W Request from unknown user - request rejected.
    The information received by the Fileshare Server is not recognized as being from a Fileshare Client that is currently logged onto this Fileshare Server.
  • FS016-S The parameter "text " is invalid.
    The parameter has been recognized as a valid parameter, but the option specified for that parameter is not valid. For example, the /o (omit) parameter has been specified, but the option is not t (transaction processing), l (rollforward recovery logging) or s (sequence number checking).
  • FS017-S Unable to open the file : filename.
    The Fileshare Server is unable to create the file specified.
  • FS018-S Log file corrupt - unrecognizable record in file.
    Each record written to the recovery log file has a marker informing the Rollforward Recovery Utility of the type of data contained in the record.
  • FS019-S Log file corrupt - can't read header.
    Each record written to the recovery log file has a marker indicating the type of data contained in the record. This error indicates that the required header record at the beginning of the log file was not found. This implies that the log file has become corrupt, which can happen, for example, if the system crashed while records were being written to the recovery log file.
  • FS020-S The log file does not match the database sequence numbers - recovery aborted.
    Each index file (not C-ISAM) and all variable length record files have (by default) a sequence number stored in the header of the file. A corresponding sequence number is stored in the log file. Checks are made between the sequence numbers in the file headers and the log file to help ensure that the recovery process proceeds successfully.
  • FS021-S There is no log filename specified in the database reference file.
    You have tried to erase a log file entry from the database reference file but there is no log filename specified in the database reference file. The operation therefore cannot be completed successfully.
  • FS022-S The log filename given cannot be found in the database reference file.
    You have failed to erase a log file entry from the database reference file because the log filename specified is not the same as the log filename in the database reference file.
  • FS024-S Failed to open log file : filename.
    The Fileshare Server encountered an error while trying to open or create the rollforward recovery log file. Common causes of this error are:
  • FS025-S Write failure to the log file, Fileshare Server is closing down.
    The Fileshare Server encountered an error while writing a record to the recovery log file. Because the integrity of the log file cannot be guaranteed, the Fileshare Server shuts down so that the updates performed up to the point of failure are not lost.
  • FS026-W Failed to close the log file.
    The Fileshare Server encountered an error while closing the current log file.
  • FS027-S A second log file parameter has been found.
    While processing the database reference file, a second log file parameter was found. There should only ever be one log file specified in the database reference file and this error indicates that the database reference file is corrupt or has been changed without using the Database Reference File Maintenance Utility.
  • FS028-W The log file shows the last session was not shut down successfully.
    When the Fileshare Server shuts down successfully, the last record written to the recovery log file is a special record that marks the end of the recovery log file. This message indicates that the Fileshare Server could not find the special, last record when it opened the log file, suggesting that the log file was not closed in a controlled manner, probably due to a system crash. The log file could have been opened either to append to or read from in order to perform a rollforward recovery.
  • FS029-S The log filename is already specified in the database reference file.
    You have tried to add the name of the recovery log file to the database reference file. However a log filename already exists in the database reference file. A database reference file can only contain one log filename.
  • FS030-S Insufficient disk space to continue logging to log file.
    The amount of space remaining on the disk where the log file is being written has less than 200K bytes of free space remaining. This is not adequate to ensure that the recovery log file can continue to be successfully written.
  • FS031-I Record lock time-out failure on user : user.
    A record lock time-out has occurred on the user indicated. This is due to the user holding a lock on a record for a period of time longer than the record lock time-out period, when another user is trying to access that locked record.
  • FS034-S A filename or log file parameter must be specified.
    The Database Reference File Maintenance Utility has been invoked using the /d option, however a valid parameter for the utility has not been given
  • FS035-S A database reference file must be specified.
    The Database Reference File Maintenance Utility has been invoked, however the name of the database reference file to use has not been specified using the /d parameter. For example, the parameter /f (filename), /l (log filename), /fs (file string) or /backup (backup directory) has been used to invoke the Database Reference File Maintenance Utility but a /d option has not been specified to supply the name of the database reference file.
  • FS037-I The file filename does not have a file header record. Sequence checking is switched off for this file.
    The Fileshare Server has determined that the file indicated does not have a Micro Focus format file header. It is not possible to have sequence numbering on files that do not contain file headers. However, the configuration of the database reference file specifies that sequence number checking should be applied to this file.
  • FS038-S A matching sequence number not found in filename.
    This error message is displayed when the sequence number in the header of the named file does not match the sequence number in the rollforward recovery log file. See the section Database Sequence Numbering in the chapter Database Integrity for full details of database sequence numbering works.
  • FS039-S Improperly closed file - filename.
    The Fileshare Server has found that the file indicated has been marked as corrupt because it was not closed correctly. This implies that the file was not closed in a controlled manner and that the Fileshare Server last accessing the file terminated abnormally.
  • FS040-S Unable to read the file header record in the file filename.
    The Fileshare Server was able to open the file specified, but was not able to read the file header. The file header consists of the first 128 bytes of the file.
  • FS041-S Unable to update the sequence number in the file filename.
    The Fileshare Server was unable to update the sequence number in the header of the file specified. The sequence number in the header of this file cannot be relied on and hence messages relating to incorrect sequence numbers can be ignored. However, careful checks should be made to ensure that the correct version of the file are in place when starting the Fileshare Server or performing a rollforward recovery.
  • FS042-S Unable to open the database reference file: filename.
    The Fileshare Server was unable to open the database reference file indicated
  • FS043-S The database reference file contains an invalid entry.
    The Fileshare Server has found data in the database reference file which is not as expected. This implies that the database reference file has been changed without using the Database Reference File Maintenance Utility or that the database reference file is corrupt in some way.
  • FS044-S Error reading the database reference file.
    An error was encountered when reading the database reference file. The file was successfully opened by the Fileshare Server. This message implies that the file is corrupt or that a disk I/O error occurred. Alternatively, if the database reference file is on a remote drive, a network error could have occurred.
  • FS045-W Duplicate filename specified in the database reference file.
    A duplicate filename was found when the Fileshare Server processed the database reference file. This message implies that the database reference file has been modified, but not using the Database Reference File Maintenance Utility. A given filename should appear only once in the database reference file.
  • FS050-W A log file is not specified in the database reference file.
    The Fileshare Server processed the database reference file but could not find a rollforward recovery log filename. The database reference file should have a recovery log file specified in order that recovery logging can be performed.
Parent topic: Fileshare Server Messages
Related information
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W
Messages from FS201-S to FS252-S


FS001-S The parameter "text " is not recognized as a valid parameter.

The operation did not complete.

Resolution:

Change the indicated parameter and retry the operation.

The valid parameters are given in the sections:

  • Server Configuration in the chapter Configuration
  • Database Reference File Maintenance and Rollforward Recovery Utility in the chapter Database Integrity
  • Password File Maintenance in the chapter Security
Parent topic: Messages from FS001-S to FS050-W
Related information
Server Configuration
Database Reference File Maintenance
Rollforward Recovery Utility
Password File Maintenance


FS004-S The parameter "text " specifies a time-out value that is invalid.

The time-out value is specified in seconds and must be in the range 0 through 99999.

See the section Automatic Record Lock Timeout in the chapter Database Integrity for more information.

Resolution:

Retry the operation using a time-out value in the correct range.

Parent topic: Messages from FS001-S to FS050-W
Related information
Automatic Record Lock Timeout


FS005-S The parameter "text " is too long or invalid.

  • The parameter specified is too long. For example a password has been specified which is more than 20 characters in length.
  • The parameter expects a value, but none has been given. For example, the /t parameter has been specified but no time-out value has been given.

Resolution:

Retry the operation using a correct value for the parameter indicated.

Parent topic: Messages from FS001-S to FS050-W


FS006-S The parameter "text " has already been specified.

Resolution:

Retry the operation ensuring that only one occurrence of the parameter exists.

Parent topic: Messages from FS001-S to FS050-W


FS007-S Invalid parameter combination.

This can be for the following reasons:

  • Not enough parameters have been specified in order for the operation to be processed. For example, you have tried to start the Fileshare Server without giving a server name.
  • The parameters specified do not indicate a valid operation that can be carried out. For example, the combination /s and /r is invalid as the first implies that the Fileshare Server is to start with the server name indicated, whereas the second parameter indicates that a Rollforward Recovery is to be performed.

Resolution:

Ensure that the parameters specified are correct and retry the operation.

Parent topic: Messages from FS001-S to FS050-W


FS008-S Communications Initialization Failure.

Resolution:

Ensure that the required CCI module(s) required for the protocol you are using is/are available. Use the CCI demo program supplied with the product to ensure that the CCI module required can be loaded and initialized.

Ensure that the network software on the machine is installed, configured and operational.

Parent topic: Messages from FS001-S to FS050-W


FS009-S The required communications module cannot be found.

Resolution:

Ensure that the CCI (and required network modules) are installed correctly on the machine.

Try out the CCI demo program supplied with the product with the same CCI protocols before trying the start the Fileshare Server again.

Parent topic: Messages from FS001-S to FS050-W


FS011-W Communications send failure.

See the message FS148-I for more information.

Resolution:

No user action is possible. However, if the error persists, this could indicate that there is a possible problem with the network or that the network has a high volume of traffic.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS148-I


FS012-W Communications disconnect failure.

  • It receives a request from an unknown Fileshare Client
  • The CCI protocol indicated that the Fileshare Client application terminated abnormally

Resolution:

If the error persists, there could be a problem with the network that is being used. Also, ensure that users are closing down Fileshare Client applications correctly and not turning the workstation machines off or using utilities to terminate the Fileshare applications abnormally (for example kill on UNIX).

Parent topic: Messages from FS001-S to FS050-W


FS013-W Communications receive error.

See the message FS148-I for more information about the cause of the error.

Resolution:

No direct action by the user is possible. However, if the error persists, there could be a problem with the network that is being used or there could be a high volume of network traffic.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS148-I


FS014-W Communications data length not as expected.

This error should not occur in normal circumstances. If found, it implies that there is a problem with the communications system or that the requester service has not been started when using the NETBIOS protocol.

The Fileshare Server has ignored the data sent from the Fileshare Client.

See also the messages FS151-I and FS082-S for additional information.

Resolution:

If using the NETBIOS protocol, ensure that it is installed correctly, configured and operational.

It is highly likely that the Fileshare Client appears to have stopped because the Fileshare Server has not sent back any reply. Depending on the CCI protocol being used, a time-out occurs in approximately two minutes and a 9/124 status is returned to the application program.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS151-I
FS082-S


FS015-W Request from unknown user - request rejected.

The Fileshare Server has ignored the information that it has received and has returned a 9/125 error status to the Fileshare Client that sent the request.

With some CCI protocols, the session associated with this request is disconnected. See the message FS238-I for additional information.

Resolution:

No action is required.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS238-I


FS016-S The parameter "text " is invalid.

Resolution:

Change the parameter specified to a valid option.

Parent topic: Messages from FS001-S to FS050-W


FS017-S Unable to open the file : filename.

The file may be open already or marked as read-only.

Resolution:

Ensure that the path and filename are valid and that the Fileshare Server has read and write access to the directory.

Parent topic: Messages from FS001-S to FS050-W


FS018-S Log file corrupt - unrecognizable record in file.

This error indicates that the marker in the record header is not recognized which implies that the log file has become corrupted in some way.

This error can occur if the last record of the recovery log file was not written successfully because of a system crash. The Recovery Utility will have processed all of the records up to the point of failure.

Resolution:

Ensure that the correct log file is available to the Fileshare Rollforward Recovery Utility.

Parent topic: Messages from FS001-S to FS050-W


FS019-S Log file corrupt - can't read header.

Resolution:

Ensure that the correct log file is available to the Fileshare Rollforward Recovery Utility. If the correct log file is in place, then the file is corrupt and cannot be used in a rollforward recovery process.

Parent topic: Messages from FS001-S to FS050-W


FS020-S The log file does not match the database sequence numbers - recovery aborted.

This error indicates one of the following:

  • The sequence number in the file headers is greater than that in the log file. This indicates that updates have been applied to the files, without the updates being logged in the log file. Because the log file does not contain all of the updates, it is not possible to perform a rollforward recovery. This also indicates that the rollforward recovery is trying to use the wrong versions of the files.
  • The first sequence number in the recovery log file is larger than the sequence number in the file headers. This indicates that updates have been written to the log file but they have not been applied to the data files. It is not possible to apply the updates from the recovery log file because the versions of the data files and the recovery log file do not match.

Resolution:

Ensure that the correct versions of the data and rollforward recovery log file are being used.

See the section Database Sequence Numbering in the chapter Database Integrity for more information.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Sequence Numbering


FS021-S There is no log filename specified in the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS001-S to FS050-W


FS022-S The log filename given cannot be found in the database reference file.

Resolution:

Specify the correct name of the log file when trying to erase the entry from the database reference file.

Parent topic: Messages from FS001-S to FS050-W


FS024-S Failed to open log file : filename.

  • The Fileshare Server does not have read/write access to the log file and/or the directory where the log file resides.
  • The filename specified for the log file is invalid. The filename may not be a valid filename for the operating system on which the Fileshare Server resides or the path specified in the log filename specifies a drive/directory that does not exist.
  • The log file is in use by another process, preventing the Fileshare Server from obtaining exclusive access to the log file.
  • The operating system or the COBOL run-time system is unable to allocate a file handle to the log file.
Parent topic: Messages from FS001-S to FS050-W


FS025-S Write failure to the log file, Fileshare Server is closing down.

The cause of the failure should be investigated. Possible causes include the disk is full, a disk error or, if logging to a remote drive, a network error occurred.

Resolution:

We advise you to have the recovery log file local to where the Fileshare Server is running so that the chances of network errors occurring while writing to the log file are reduced. Also, the Fileshare Server cannot force the operating system to flush records to disk if the log file is not on the local machine.

Parent topic: Messages from FS001-S to FS050-W


FS026-W Failed to close the log file.

Possible causes are that the disk is full or, if logging to a remote drive, a network error occurred.

We advise you to have the recovery log file local to where the Fileshare Server is running so that the chances of network errors occurring while writing to the log file are reduced.

The cause of the failure should be investigated.

Resolution:

It should be possible to use this recovery log file in a rollforward recovery operation as the Fileshare Server has written all of the required information to the file.

Parent topic: Messages from FS001-S to FS050-W


FS027-S A second log file parameter has been found.

Resolution:

Ensure that the correct database reference file is used and that only one recovery log filename is specified in the database reference file.

Only use the Database Reference File Maintenance Utility to change the contents of the database reference file. In this situation however, it may be possible to remove the duplicate entry using a normal text editor. Alternatively the current database reference file can be discarded and a new one created using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS001-S to FS050-W


FS028-W The log file shows the last session was not shut down successfully.

If the Fileshare Server is starting up, the log file is backed up and a new log file created. If you have specified a backup directory in the database reference file, the Rollforward Recovery Utility is invoked automatically.

If a rollforward recovery is being performed, recovery proceeds up to the last full record in the recovery log file (any incomplete transactions are rolled back).

Resolution:

No action is required

Parent topic: Messages from FS001-S to FS050-W


FS029-S The log filename is already specified in the database reference file.

Resolution:

Remove the current log filename from the database reference file using the Database Reference File Maintenance Utility and then add the name of the new log file using the same utility.

Parent topic: Messages from FS001-S to FS050-W


FS030-S Insufficient disk space to continue logging to log file.

The Fileshare Server will close the current recovery log file and wait for it to be backed up before continuing.

Resolution:

Manually back up the current log file and then delete the file. This releases disk space and enables the Fileshare Server to continue logging with a new logfile.

Parent topic: Messages from FS001-S to FS050-W


FS031-I Record lock time-out failure on user : user.

This record lock time-out has caused any transactions that this user has outstanding to be automatically rolled back and all record locks held by this user have been released. See the section Automatic Record Lock Timeout in the chapter Database Integrity for more information.

You can specify the record lock time-out period using the /t option when you configure the Fileshare Server.

On the next I/O operation, a status of 9/125 will be returned to the Fileshare Client application that held the lock.

Resolution:

No action is required, however the time-out period can be changed or disabled if required.

Parent topic: Messages from FS001-S to FS050-W
Related information
Automatic Record Lock Timeout


FS034-S A filename or log file parameter must be specified.

Resolution:

Ensure that when invoking the Database Reference File Maintenance Utility, the option /f (filename), /l (log filename), /fs (file string) or /backup (log file backup directory) is used to specify which action should be taken

Parent topic: Messages from FS001-S to FS050-W


FS035-S A database reference file must be specified.

Resolution:

Include the /d option when invoking the Database Reference File Maintenance Utility to provide the name of the database reference file to use

Parent topic: Messages from FS001-S to FS050-W


FS037-I The file filename does not have a file header record. Sequence checking is switched off for this file.

The Fileshare Server will not apply sequence number checking to this file.

Resolution:

The programs accessing the files should be changed so that they define the files as variable length record files.

It is not possible to have sequence number checking on line sequential files.

If sequence number checking is required, the file must contain a file header. Fixed length indexed, sequential and relative files should be converted to variable length record format.

Alternatively, if sequence number checking is not required for this file, this message can be avoided by explicitly turning sequence number checking off using the /o s option in this file's entry in the database reference file. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Reference File Maintenance


FS038-S A matching sequence number not found in filename.

The named file is listed in the database reference file and sequence number checking is active for the file. This message indicates that an incorrect version of the file is being used. The Fileshare Server does not start until this problem is rectified.

Resolution:

Ensure that the correct version of the file is available to the Fileshare Server and that if sequence numbering is used, all updates performed to the file are done via the Fileshare system. See the section Database Sequence Numbering in the chapter Database Integrity for more information.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Sequence Numbering


FS039-S Improperly closed file - filename.

Resolution:

The file is corrupt and a backup should be put in place and recovery performed using the Rollforward Recovery Utility. See the section Rollforward Recovery Utility in the chapter Database Integrity for details. If you have specified a backup directory in the database reference file, the recovery will be performed automatically.

If updates to the file have not been logged then the file should be rebuilt using the REBUILD utility.

Parent topic: Messages from FS001-S to FS050-W
Related information
Rollforward Recovery Utility


FS040-S Unable to read the file header record in the file filename.

Resolution:

If sequence number checking is not required for this file then this feature should be omitted for this file using the /o s option in the database reference file.

All files that can have sequence number checking are at least 128 bytes in length as this is the size of a file header (which is required for sequence number checking to be performed).

Parent topic: Messages from FS001-S to FS050-W


FS041-S Unable to update the sequence number in the file filename.

Resolution:

This error is very rare and implies a disk I/O error (or a network error if the file is not on the local Fileshare Server machine).

Parent topic: Messages from FS001-S to FS050-W


FS042-S Unable to open the database reference file: filename.

Resolution:

Ensure that the path and filename are correct and that the Fileshare Server has full read and write access to the file specified.

Also ensure that the Fileshare Server can gain exclusive access to the database reference file and that another process does not have the file open.

Parent topic: Messages from FS001-S to FS050-W


FS043-S The database reference file contains an invalid entry.

Resolution:

Ensure that only the Database Reference File Maintenance Utility is used to change the contents of the database reference file.

Alternatively, discard the current database reference file and re-create the contents of the file using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS001-S to FS050-W


FS044-S Error reading the database reference file.

Resolution:

Try the operation again. If the problem persists, the database reference file is probably corrupt - the current file should be discarded and a new database reference file created using the Database Reference File Maintenance Utility

Parent topic: Messages from FS001-S to FS050-W


FS045-W Duplicate filename specified in the database reference file.

Resolution:

Recreate the database reference file ensuring that each filename appears in the file only once.

Parent topic: Messages from FS001-S to FS050-W


FS050-W A log file is not specified in the database reference file.

Resolution:

If rollforward recovery logging is required, add an entry to the database reference file specifying a rollforward recovery log filename. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Reference File Maintenance


Messages from FS051-W to FS099-W

  • FS051-W Failure to allocate a larger buffer, the I-O request failed.
    When using compression on the communication buffers, this message indicates that there was not enough memory available to the Fileshare Server to enable it to decompress the buffer. The I/O request has failed and the Fileshare Client was returned a 9/105 (out of memory) error.
  • FS052-S Failure to allocate required memory. The Fileshare Server is closing down.
    You see this message when the Fileshare Server is initializing and cannot allocate enough memory for the required internal tables
  • FS055-S The parameter "text " specifies a configuration file that does not exist.
    The Fileshare Server is unable to locate or open the configuration file indicated
  • FS056-S The parameter "text " specifies a data compression value that is not within the range 0-255.
    You have tried to add an entry to the database reference file. This entry specifies a value for the data compression outside of the permitted limits. The data compression option must specify a value within the range 0 through 255. To use the routine CBLDC001 as the compression method on records in the file, specify a compression value of 1.
  • FS057-S The parameter "text " specifies a key compression value that is not within the range 0-7.
    You have tried to add an entry to the database reference file which specifies a value for the key compression outside of the permitted limits.
  • FS058-S Failure to allocate memory for the decompression of the log file.
    The Rollforward Recovery Utility has been invoked but is unable to allocate the required memory so that it can process the recovery log file. This error is displayed during the initialization of the recovery process and indicates a shortage of available memory.
  • FS059-S Failure to allocate the memory required for processing the database reference file.
    When reading in a database reference file (either when the Fileshare Server or the Rollforward Recovery Utility is starting) this message indicates that the Fileshare Server was not able to allocate the required memory to be able to process all of the information in the database reference file
  • FS062-S Failure creating the password file filename.
    The Fileshare Server was unable to create the password file indicated
  • FS063-S Failure opening the password file filename.
    The Fileshare Server was unable to open the password file indicated
  • FS064-S Failure reading the password file filename.
    The Fileshare Server encountered an error reading the information from the password file. This implies that an I/O error occurred, the password file has become corrupted in some way or that a network error occurred if the password file is located on a remote machine.
  • FS065-S The password file is not of a recognized format.
    The first record in the password file is a special record which indicates to the Fileshare Server that the file is a password file. This record also contains information regarding the version of the password file being used.
  • FS066-S The specified user name already exists in the password file.
    You see this message when using the Password File Maintenance Utility and you have tried to add a user name to the password file when the user name already exists in the password file
  • FS068-I The password file is now empty and has been deleted.
    You see this message when you have used /e (erase) option with the Password File Maintenance Utility to remove the last entry from the password file. As the password file is now empty, it has been deleted. If a new password file is required it is created automatically when you add an entry using the Password File Maintenance Utility.
  • FS069-S The specified entry could not be found in the password file.
    This message indicates that you have used /e (erase) option with the Password File Maintenance Utility to remove an entry, but the entry specified does not exist in the password file.
  • FS070-S Failure writing to the password file.
    The Password Maintenance Utility encountered an error when it tried to write information to the password file. This implies that an I/O error occurred (possibly a full disk) or a network error was encountered (if the password file is on a remote machine). The integrity of the password file cannot be guaranteed.
  • FS071-W Unable to load the module FHXSCOMP to decompress the data area.
    This message indicates that the Fileshare Server has received a compressed communications buffer. However, it is unable to load the decompression module FHXSCOMP in order to perform the necessary decompression. There may not be enough memory to load the module or the module may not be found.
  • FS072-S The parameter "text " contains a wild card which is not allowed with this parameter.
    A parameter containing a wild card symbol was specified when invoking the Database Reference File Maintenance Utility but the parameter does not support wild cards.
  • FS073-S Failure to allocate memory to process the password file.
    When reading in a password file (when either the Fileshare Server or the Password File Maintenance Utility is starting), this message indicates that the Fileshare Server was not able to allocate the required memory to be able to process all of the information in the password file.
  • FS074-S The Fileshare Server (NLM) failed to log on to NetWare with the login id specified.
    NLM: This message is only applicable to the Fileshare NLM.
  • FS075-W Unable to load the module FSSECLOG - LOGON has been denied.
    This message indicates that the Fileshare Server failed to call the module FSSECLOG because:
  • FS076-W Unable to load the module FSSECOPN - OPEN has been denied.
    This message indicates that the Fileshare Server failed to call the module FSSECLOG because:
  • FS077-S A Fileshare Server of the same name has already been defined - the Fileshare Server is closing down.
    When the Fileshare Server starts up, it registers its name on the network so that Fileshare Clients can connect to it. This message indicates that the Fileshare Server is trying to register with a name that is already in use by another Fileshare Server on the network.
  • FS078-S No password file has been specified for the use of background mode.
  • FS079-S A supervisor password entry must exist for the use of background mode.
  • FS080-S No password file has been specified for the use of the synchronous communications mode.
    You have tried to start the Fileshare Server using synchronous communications (as opposed to asynchronous communications which is the default). To enable the use of synchronous communications, you must specify a password file which contains a supervisor-ID of FSVIEW. This enables the Fileshare Server to be closed down remotely using FSVIEW or FSMgr. This is necessary because in this communications mode, the Fileshare Server only checks for keyboard input very occasionally.
  • FS081-S A supervisor password must be specified in the password file for the synchronous communications mode.
    You have tried to start the Fileshare Server using synchronous communications (as opposed to asynchronous communications which is the default). To enable the use of synchronous communications, you must specify a password file which contains a user-ID of FSVIEW. This enables the Fileshare Server to be closed down remotely using FSVIEW or FSMGR. This is necessary because in this communications mode, the Fileshare Server only checks for keyboard input very occasionally.
  • FS082-S The Netbios communications protocol is not responding. Ensure the requester software is loaded and functional.
    You have tried to start the Fileshare Server using the Netbios protocol (CCINETB) but the required network software is not loaded or is not operational. The Fileshare Server is trying to use the NETBIOS software but is receiving invalid data.
  • FS083-S Incompatible CCIIPX.NLM version.
    The Fileshare NLM Server has detected that the version of cciipx.nlm being used is not a compatible version. You are probably trying to use an old version of the CCIIPX NLM with this version of the Fileshare NLM.
  • FS084-I Fileshare Server is starting.
    This message indicates that the Fileshare Server is in the process of initializing. The configuration, database reference and password files (if specified) are being processed and the communications software is being loaded and initialized.
  • FS085-I Fileshare Server is active.
    This message indicates that the Fileshare Server has completed its initialization processing and is now ready to accept incoming requests from Fileshare Clients. At this stage all of the configuration, database reference and password files have been processed and the communications software has been successfully initialized and is operational.
  • FS086-I Fileshare Server is closing down.
    This message indicates that the Fileshare Server has started the process of closing down and will shortly terminate. This can be invoked by the following:
  • FS087-I Fileshare Server has closed down.
    This message indicates that the Fileshare Server has completed all of its termination processing. All communications have stopped, all files closed, all transactions rolled back and any rollforward recovery log file shut. The Fileshare Server can now be restarted when necessary.
  • FS089-I Database Reference File Maintenance Utility.
    The Database Reference File Maintenance Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file. The Database Reference File Maintenance Utility will try to process the remaining parameters specified as options to this utility.
  • FS090-I Database Reference File installation completed successfully.
    The Database Reference File Maintenance Utility has been invoked successfully and the required change made to the database reference file has been made.
  • FS091-I Rollforward Recovery Utility
    The Rollforward Recovery Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.
  • FS092-I Rollforward Recovery has completed.
    The recovery process is now complete: the files contain the updates recorded in the log file when the Fileshare Server was in use.
  • FS094-I Password File Maintenance Utility.
    The Password File Maintenance Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.
  • FS096-I Password File installation has completed.
    The Password File Maintenance Utility has successfully updated the password file using the options specified when the Password File Maintenance Utility was invoked.
  • FS097-I Are you sure that you wish to close down the Fileshare Server ? (Y/N)
    You have used the Esc key sequence to close down the Fileshare Server. This message is an additional prompt to avoid closing down the Fileshare Server in error.
  • FS099-W File I/O status was not as expected. Returned status: status Expected status: status Action code: text File: filename.
    This error occurs when a file is being recovered using the Rollforward Recovery Utility. When the log file is written during the normal operation of the Fileshare Server, a record is made in the log file of the status of each I/O operation performed. At the time of recovery, the status returned during the recovery process is compared with that stored in the recovery log file.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W
Messages from FS201-S to FS252-S


FS051-W Failure to allocate a larger buffer, the I-O request failed.

Resolution:

Free some memory on the machine where the Fileshare Server is running so that it is able to increase the size of its decompression buffers.

Alternatively, reconfigure the Fileshare System so that compression on the communications buffers is not used.

Parent topic: Messages from FS051-W to FS099-W


FS052-S Failure to allocate required memory. The Fileshare Server is closing down.

Resolution:

Free some memory on the machine where the Fileshare Server is running so that more memory is available to the Fileshare Server.

Parent topic: Messages from FS051-W to FS099-W


FS055-S The parameter "text " specifies a configuration file that does not exist.

Resolution:

Ensure that the path and filename are correct and that the Fileshare Server has read access to the file. Also ensure that no other process currently has the file open as the Fileshare Server requires exclusive access to the configuration file.

Parent topic: Messages from FS051-W to FS099-W


FS056-S The parameter "text " specifies a data compression value that is not within the range 0-255.

The specification of compression of records only takes effect when the file is created. Specifying data compression on a file that already exists and contains uncompressed records has no effect.

Resolution:

Specify a data compression value of 0 through 255

See the section Database Reference File Maintenance in the chapter Database Integrity for more information on the /k parameter and valid options.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS057-S The parameter "text " specifies a key compression value that is not within the range 0-7.

The key compression option must specify a value within the range 0 through 7.

Specifying key compression only has an effect at the time that the file is created. Specifying key compression on a file that already exists, but does not have key compression, has no effect.

Resolution:

Specify a key compression value of 0 through 7.

See the section Database Reference File Maintenance in the chapter Database Integrity for more information on the /k parameter and valid options.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS058-S Failure to allocate memory for the decompression of the log file.

Resolution:

Increase the amount of available memory by reducing the number of processes and/or applications running on the same machine where you are running the Rollforward Recovery. Then try to run the Rollforward Recovery Utility again.

Parent topic: Messages from FS051-W to FS099-W


FS059-S Failure to allocate the memory required for processing the database reference file.

Resolution:

Try to make more memory available to the Fileshare Server by reducing the number of processes or applications that are running on the same machine. If this is not possible, reduce the amount of information that is contained in the database reference file.

Parent topic: Messages from FS051-W to FS099-W


FS062-S Failure creating the password file filename.

Resolution:

Ensure that the path and filename are valid and that the specified file is not already open by another process. The Fileshare Server requires read and write permission to the password file and tries to create the file with exclusive access.

Parent topic: Messages from FS051-W to FS099-W


FS063-S Failure opening the password file filename.

Resolution:

Ensure that the path and filename are valid and that the specified file is not already open by another process. The Fileshare Server requires read and write permission to the password file and tries to open the file with exclusive access.

Parent topic: Messages from FS051-W to FS099-W


FS064-S Failure reading the password file filename.

Resolution:

Retry the operation. If the message persists, the password file may be corrupt and should be discarded. A new password file should then be created using the Password File Maintenance Utility.

Parent topic: Messages from FS051-W to FS099-W


FS065-S The password file is not of a recognized format.

This message indicates that the Fileshare Server has not recognized this record in the file as being that identifying a password file. Alternatively the password file has become corrupt.

Resolution:

Check that the path and filename of the password file specified are correct.

If they are correct then the current password file should be discarded and a new one created using the Password File Maintenance Utility.

Parent topic: Messages from FS051-W to FS099-W


FS066-S The specified user name already exists in the password file.

Resolution:

To update a user entry that already exists in the password file, first erase the entry and then add the new entry to the file. See the section Password File Maintenance in the chapter Security for more details.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS068-I The password file is now empty and has been deleted.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS069-S The specified entry could not be found in the password file.

Resolution:

Ensure that the user name and password are correct (that is, exactly those which were specified for the entry to be erased when the entry was first added to the password file). If the user-ID or password are no longer known, you must create a new password file using the Password File Maintenance Utility.

Parent topic: Messages from FS051-W to FS099-W


FS070-S Failure writing to the password file.

Resolution:

Restore the password file from a backup and try to add the new entry again. If no backup is available, discard the current password file and create a new one using the Password File Maintenance Utility.

Ensure that there is enough disk space available on the drive where the password file resides.

Parent topic: Messages from FS051-W to FS099-W


FS071-W Unable to load the module FHXSCOMP to decompress the data area.

Alternatively there may be an insufficient number of file handles available to enable the operating system or run-time system to load the module.

The request received from the Fileshare Client has been discarded.

Resolution:

Ensure that the system module FHXSCOMP is available on your system. Also ensure that there is enough memory available for the module to be loaded and file handles are available to enable the run-time or operating system to load the file.

Parent topic: Messages from FS051-W to FS099-W


FS072-S The parameter "text " contains a wild card which is not allowed with this parameter.

Wild cards are only permitted on database entries defining an alternate program.

See the /ap option in the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Resolution:

Do not specify a wild card symbol for this parameter.

A full path or filename should be given.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS073-S Failure to allocate memory to process the password file.

Resolution:

Try to make more memory available to the Fileshare Server by reducing the number of processes or applications that are running on the same machine. Alternatively, reduce the amount of information that is contained in the password file.

Parent topic: Messages from FS051-W to FS099-W


FS074-S The Fileshare Server (NLM) failed to log on to NetWare with the login id specified.

You see this message when using the /nu option to force the Fileshare Server to log onto NetWare with the specified user-ID. However, the Fileshare NLM Server encountered an error when trying to connect with the user-ID specified. This implies that there is no user account with the user-ID set up on the NetWare server or that you entered an incorrect password when prompted to do so.

Resolution:

Check that the user-ID is correct and that a user account for that ID is defined on the NetWare operating system. Also check that the correct password for this user-ID was entered when prompted.

Parent topic: Messages from FS051-W to FS099-W


FS075-W Unable to load the module FSSECLOG - LOGON has been denied.

  • FSSECLOG is not available
  • There is insufficient memory available to load FSSECLOG
  • There may be an insufficient number of file handles available to enable the operating system or run-timesystem to load FSSECLOG

FSSECLOG is required to validate logon requests to the Fileshare Server by Fileshare Clients. Because one possible cause of this error is that the FSSECLOG module has been removed on purpose, the Fileshare Server does not permit the logon to proceed in this situation.

The Fileshare Client application program has received a 9/037 error status.

Resolution:

Ensure that the module FSSECLOG is available to the Fileshare Server (this can be the FSSECLOG module supplied with the Fileshare system or a user-written one). If the module is available, try making more memory available by reducing the number of other processes or applications running on the machine and ensure that there are enough free file handles available to enable the module to be loaded.

See the chapter Security for more information about the FSSECLOG module.

Parent topic: Messages from FS051-W to FS099-W
Related information
Security


FS076-W Unable to load the module FSSECOPN - OPEN has been denied.

  • FSSECOPN is not available
  • There is insufficient memory available to load FSSECOPN
  • There may be an insufficient number of file handles available to enable the operating system or run-timesystem to load FSSECOPN

FSSECOPN is required to validate open requests to the Fileshare Server by Fileshare Clients. Because one possible cause of this error is that the FSSECOPN module has been removed on purpose, the Fileshare Server does not permit the open to proceed in this situation.

The Fileshare Client application program has received a 9/037 error status.

Resolution:

Ensure that the module FSSECOPN is available to the Fileshare Server (this can be the FSSECOPN module supplied with the Fileshare system or a user-written one). If the module is available, try making more memory available by reducing the number of other processes or applications running on the machine and ensure that there are enough free file handles available to enable the module to be loaded.

See the chapter Security for more information about the FSSECOPN module.

Parent topic: Messages from FS051-W to FS099-W
Related information
Security


FS077-S A Fileshare Server of the same name has already been defined - the Fileshare Server is closing down.

Alternatively, this message can indicate that a Fileshare Server that was using this name terminated abnormally and did not de-register its name from the network.

Resolution:

Ensure that the Fileshare Server name is unique for this server. This is the name that the Fileshare Server is configured to register on the network. If a Fileshare Server that was using this name terminated abnormally, it may be necessary to re-initialize the network software on the machine where that Fileshare Server was running to ensure that its name is no longer registered (what action is required in this situation depends on the communications protocol that is being used).

Parent topic: Messages from FS051-W to FS099-W


FS078-S No password file has been specified for the use of background mode.

UNIX:

This message is applicable to Fileshare Servers on UNIX only.

It is possible to configure the Fileshare Server to run as a daemon process on UNIX so that information is neither accepted from the keyboard nor displayed on the screen. When configuring the Fileshare Server to run in this mode, a password file must be used which should contain a FSVIEW (supervisor) user-ID and password. This enables the Fileshare Server to be closed down remotely using FSView, FSMgr or COBFSCLOSE.

This message indicates that you have tried to run the Fileshare Server in background mode but you have not specified a password file.

Resolution:

Create a password file using the Password File Maintenance Utility containing a user-ID of FSVIEW and a password. Then specify this password file (using the -pf option) in the Fileshare Server configuration file.

See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS079-S A supervisor password entry must exist for the use of background mode.

UNIX:

This message is applicable to Fileshare Servers on UNIX only.

It is possible to configure the Fileshare Server to run as a daemon process in the background on UNIX where no information is accepted from the keyboard nor displayed on the screen. When configuring the Fileshare Server to run in this mode, a password file must be used which should contain an FSVIEW (supervisor) user-ID and password. This enables the Fileshare Server to be closed down remotely using FSMgr, FSView or COBFSCLOSE.

This message indicates that you have tried to run the Fileshare Server in background mode but the password file that you specified does not contain an FSVIEW (supervisor) user-ID or password.

Resolution:

Add a user-ID of FSVIEW and password to the password file specified using the Password File Maintenance Utility.

See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS080-S No password file has been specified for the use of the synchronous communications mode.

Resolution:

When starting the Fileshare Server, use the /pf option in the Fileshare Server configuration file to specify the name of a password file containing a user-ID of FSVIEW. See the sections Password System and Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password System
Password File Maintenance


FS081-S A supervisor password must be specified in the password file for the synchronous communications mode.

This message indicates that a password file has been specified, however, there is no (supervisor) user-ID of FSVIEW in the password file.

Resolution:

Add a user-ID of FSVIEW and a password to the password file using the Password File Maintenance Utility and try the operation again. See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS082-S The Netbios communications protocol is not responding. Ensure the requester software is loaded and functional.

Resolution:

Ensure that the NETBIOS software has been loaded, is functioning and is configured correctly on the machine where you are trying to start the Fileshare Server. Try to start the Fileshare Server again. Alternatively, use another communications protocol.

See the message FS014 for further information.

Parent topic: Messages from FS051-W to FS099-W
Related information
FS014


FS083-S Incompatible CCIIPX.NLM version.

Resolution:

Ensure that the version of cciipx.nlm supplied with the Fileshare Server NLM is the one on the system and that this version is loaded in preference to any earlier version (meaning that this version is on the search path before any older version of the CCIIPX NLM)

Parent topic: Messages from FS051-W to FS099-W


FS084-I Fileshare Server is starting.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS085-I Fileshare Server is active.

Fileshare Client applications can now be started and communicate with this Fileshare Server.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS086-I Fileshare Server is closing down.

  • The Fileshare Server encountered an error when starting up, for example an error was found in a configuration, database reference or password file. Alternatively the communications support could not be started.
  • The user has requested to shut down the Fileshare Server (either by the Esc key sequence or a remote request from FSView or FSMgr)
  • The Fileshare Server has encountered an unrecoverable error during its operation. For example, the remaining disk space where the rollforward recovery log file resides is below the acceptable limits for logging to continue.
  • The Fileshare Server process was terminated by an event external to the Fileshare Server(for example a kill command on UNIX)

The Fileshare Server is closing all outstanding connections with Fileshare Clients, rolling back any outstanding transactions, closing all open files and shutting down the communication support.

Depending on the communications protocol that is in use, the Fileshare Client applications may appear to suspend if they are still trying to send requests to this Fileshare Server.

Resolution:

No action is required

Parent topic: Messages from FS051-W to FS099-W


FS087-I Fileshare Server has closed down.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS089-I Database Reference File Maintenance Utility.

If the Database Reference File Maintenance Utility should not have been invoked, check the command line to ensure that neither the /d option nor any other valid Database Reference File Maintenance option has been specified. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS090-I Database Reference File installation completed successfully.

The database reference file specified now contains the change required.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS091-I Rollforward Recovery Utility

If the Rollforward Recovery Utility should not have been invoked, check the command line to ensure that neither the /r option nor any other valid Rollforward Recovery Utility option has been specified. See the section Rollforward Recovery Utility in the chapter Database Integrity for more details.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W
Related information
Rollforward Recovery Utility


FS092-I Rollforward Recovery has completed.

If the updates have been applied successfully, you should back up the recovered files and use a new log file when you restart the Fileshare Server. This ensures that the new recovery log file is in step with the current data files.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS094-I Password File Maintenance Utility.

If the Password File Maintenance Utility should not have been invoked, check the command line to ensure that the /pf option has been used correctly and that no other option specific to the Password File Maintenance Utility has been used. See the section Password File Maintenance in the chapter Security for more details.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS096-I Password File installation has completed.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS097-I Are you sure that you wish to close down the Fileshare Server ? (Y/N)

The Fileshare Server does not accept input from Fileshare Clients whilst waiting for the response to this prompt. Consequently, you should respond quickly to this prompt.

Resolution:

Responding Y to this prompt causes the Fileshare Server to start its termination processing. If there are any files open or users logged onto this Fileshare Server, an additional prompt and confirmation are displayed. When the Fileshare Server shuts down, it rolls back all outstanding transactions, closes all open files, logs off all users and closes down the communication support modules.

If you give any reponse other than Y, the Fileshare Server continues operating as normal.

Parent topic: Messages from FS051-W to FS099-W


FS099-W File I/O status was not as expected. Returned status: status Expected status: status Action code: text File: filename.

This message indicates that the status returned during the recovery process was not the same as that when the operation was performed during the normal Fileshare Server processing when the log file was written.

The Returned status is the status that the Rollforward Recovery Utility encountered when trying to apply the updates from the recovery log file to the data files.

The Expected Status is the status that was returned when this operation was originally performed by the Fileshare Server (and when the log file was being written).

The Action code is the operation code that is being performed.

The name of the file is included in the message.

This error indicates one of the following:

  • The files to which the recovery log file is being applied are not the ones that were in use at the time that the Fileshare Server was started and the log file was created
  • The recovery log file or the files being rolled forward are corrupt
  • A situation has arisen which did not occur when the rollforward recovery file was created during normal Fileshare Server operation

Resolution:

Note the expected and returned error codes and take appropriate action. Also ensure that the correct version of the data files are in place and try to re-run the rollforward recovery.

Parent topic: Messages from FS051-W to FS099-W


Messages from FS101-I to FS149-I

  • FS101-I text -- parameter has been accepted.
    The indicated parameter (and value if required) has been accepted by the Fileshare Server
  • FS103-I The log filename has been added to the database reference file.
    The Database Reference File Maintenance Utility has been invoked to add a recovery log filename to the database reference file and the operation has completed successfully. The database reference file now contains the name of the recovery log file specified.
  • FS104-I The log file cannot be found, creating a new recovery log file.
    The Fileshare Server on starting up has processed the database reference file and determined the name of the rollforward recovery log file to use. The recovery log file does not exist and so the Fileshare Server has created a new one.
  • FS105-W The disk free space for the log file is below acceptable limits.
    The Fileshare Server has detected that the amount of disk space remaining on the drive where the recovery log file is being written is below a certain level.
  • FS106-I filename - added to database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully added the filename indicated to the database reference file.
  • FS107-I filename - removed from the database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully removed the filename indicated from the database reference file.
  • FS108-I Processing the files specified in the database reference file.
    This message indicates that the Fileshare Server has opened the database reference file and is now scanning through it, processing each filename listed. The type of processing that it performs depends on the utility being used:
  • FS109-W The file filename does not exist.
    You see this message when the filenames listed in the database reference file are being processed and indicates that the file indicated cannot be located physically on disk.
  • FS110-I filename - OK.
    The Fileshare system has successfully processed the entry indicated in the database reference file and the file has been physically located on disk.
  • FS111-W Files are still open. Continue to close down the Fileshare Server (Y/N) ?
    You have selected to close down the Fileshare Server using the Esc key sequence. This message indicates that Fileshare Clients are still connected to this Fileshare Server with files open, or at least one Fileshare Client application program has terminated abnormally leaving one or more files open. You are asked to confirm that you do want to shut down the Fileshare Server even though there are files open.
  • FS114-W Waiting for the old log file to be removed.
    The drive where the rollforward recovery log file is being written has become full and the Fileshare Server is no longer able to continue writing to the rollforward recovery log file. The Fileshare Server is waiting for the old log file to be backed up and then deleted so that it can continue writing to the directory where the log file resides.
  • FS118-I The database sequence number matches the sequence number in the log file, no recovery is needed.
    For files formats with file headers (all index files and variable length record relative and sequential files), the Fileshare Server stores a sequence number in the header. This sequence number is also placed in the recovery log file. The sequence numbers can be checked by the Fileshare Server in certain situations to ensure that the correct files are in use.
  • FS122-I Communications too busy on CCI SEND - retrying.
    The Fileshare Server tried to send a reply back to the Fileshare Client performing an I/O request. CCI returned a Too Busy error (error 10) to the Fileshare Server.
  • FS123-I Communications too busy on CCI RECEIVE - retrying.
    The Fileshare Server tried to receive information from the network but CCI returned a Too Busy error (error 10) to the Fileshare Server
  • FS124-I Checking the validity of the log file, please wait.
    You see this message when the Rollforward Recovery Utility has been invoked and it has not found a valid record as the last record in the recovery log file. The Rollforward Recovery Utility scans through the log file to find the last sequence number that was in use to validate the integrity of the recovery log file.
  • FS125-I Recovery possible to last valid recovery log file record.
    You see this message when the Rollforward Recovery Utility has been invoked. This message indicates that the recovery log file has been validated up to the point of the last complete record in the recovery log file. It is therefore possible to apply the updates stored in the recovery log file up to this point.
  • FS126-I Performing recovery, please wait.
    The Rollforward Recovery Utility has been invoked and has initialized successfully, processed the database reference file, checked the sequence numbers in the file listed in the database reference file and validated the recovery log file.
  • FS127-S Invalid name mapping command.
    You see this message when the Fileshare Server or Rollforward Recovery Utility is processing the command line or entries in the database reference file. An /fs (file string replacement) option has been specified without a corresponding /af option specifying the new string value. The /fs option must be used in conjunction with the /af option.
  • FS128-W Fileshare Server closedown invoked by Stop Run processing.
    This message indicates that the Fileshare Server has entered its termination routine not under the control of an administrator (that is, the Esc key sequence or FSView or FSMgr are not being used to shut down the Fileshare Server).
  • FS129-I The Fileshare Server is still active.
    The response to the prompt as to whether the Fileshare Server should be closed down (see messages FS097 and FS111) indicated that the Fileshare Server should not be shut down.
  • FS130-I Reading database reference file, please wait.
    The Fileshare Server, Database File Maintenance Utility or the Rollforward Recovery Utility is reading the information stored in the database reference file. The utility will try to open the database reference file and process the information held in it.
  • FS131-W Invalid communications mode - parameter ignored.
    You see this message when the Fileshare Server is processing a /cm (communications) option. The value specified for this parameter is not valid and the parameter has been ignored. See the chapters Communications and Configuration for details of valid communications modes.
  • FS132-I The Fileshare Server is running with the following communication protocol(s):
    This message gives a list of the communication protocols that the Fileshare Server is using, after it has performed all of its initialization processing.
  • FS133-I Processing the password file, please wait.
    You see this message displayed by the Fileshare Server when it is starting or by the Password File Maintenance Utility when the password file is being updated.
  • FS134-I The password file cannot be found - creating a new password file.
    The Password File Maintenance Utility displays this message when it cannot locate the password file specified with the /pf option.
  • FS135-I Fileshare Server security is active.
    Fileshare Server security is active and all Fileshare Client applications that try to access this Fileshare Server should supply a valid user-ID and password that are in the password file. If you do not provide a valid user-ID or password, access will be denied and a 9/037 error returned to the application.
  • FS136-I Fileshare Server security is not active.
    A password file has been specified, however the only user-ID specified in the file is the FSVIEW (supervisor) id. Because this is the only ID, Fileshare Server security is not active and Fileshare Client applications that try to access the Fileshare Server do not have to supply a valid user-ID or password.
  • FS138-W The log file has been backed up and a new one has been created.
    You see this message when the Fileshare Server is starting up and a recovery log file already exists. The Fileshare Server has determined that it is unable to append to the recovery log file because the last record in the log file indicates that it was not shut in a controlled manner.
  • FS139-I A matching date and time entry has been found in the log file.
    The Rollforward Recovery Utility displays this message when the /dt option has been used to recover updates to a certain point in time. The Rollforward Recovery Utility has performed the recovery using the recovery log file and has applied the updates up to the date and time specified. This message implies that there were additional records stored in the recovery log file which were not processed as they were written after the time specified.
  • FS140-I No matching date and time entry has been found in the log file.
    You see this message displayed by the Rollforward Recovery Utility when the /dt option has been used to recover updates to a certain point in time. The Rollforward Recovery Utility has performed the recovery using the recovery log file and reached the end of the log file before a record could be found that was written at the date and time specified. This implies that the date and time specified when performing the recovery is later than the date and time that the last record was written to the recovery log file. All the updates stored in the recovery log file have been applied to the data files.
  • FS142-W The Operating System does not permit the log file to be flushed to disk.
    You see this message when the Fileshare Server is using a recovery log file to store updates made to files. At certain points during its operation the Fileshare Server makes a call to the operating system to force it to flush the contents of the recovery log file to disk. This ensures that any data that has been written to the recovery log file is physically stored on disk and can be read in again after a system failure. The Fileshare Server performs this flush operation after every COMMIT operation is performed and at regular intervals (the default being after every 100 records have been written to the recovery log file, which can be changed using a /lc entry in the database reference file).
  • FS143-W The Operating System does not allow free disk space information to be obtained.
    When writing a recovery log file, it is important that there is enough disk space available. Consequently, the Fileshare Server makes periodic checks to see whether sufficient disk space remains.
  • FS144-W More than one communications protocol has been specified - synchronous communications mode not active.
    You have tried to start the Fileshare Server using the synchronous communications mode (as opposed to the asynchronous communications mode which is the default) using the /sc option.
  • FS145-W Fileshare Client disconnected, cannot contact user: text.
    The CCI has returned an error to the Fileshare Server indicating that a Fileshare Client has been disconnected. This message indicates that there may be a problem with the network or that the Fileshare Client application program is no longer functioning.
  • FS146-W Unexpected action code, action-code - discarded.
    You see this message when performing a rollforward recovery. The Rollforward Recovery Utility has read a record from the recovery log file which contains information not relating to any file currently being recovered. The information in the record cannot be processed and the Rollforward Recovery Utility has moved onto the next record in the recovery log file.
  • FS147-I A duplicate network message was received and discarded.
    This message only occurs when you are using the CCIIPX protocol and indicates that you are using an old version of the CCIIPX modules. The buffer sent between the Fileshare Client and Fileshare Server for each I/O request contains additional information which enables the Fileshare Server to check on the validity of the request. This message indicates that the Fileshare Server has received (in error) a duplicate of the previous buffer received from the communications system. This duplicate buffer has been discarded as it is not a valid I/O request.
  • FS148-I CCI return-code (function func) = code.
    You see this message when the Fileshare Server receives an unexpected error status from a CCI module. It is normally displayed in conjunction with a Fileshare Server message indicating the circumstances in which the error occurred.
  • FS149-I CCI SEND not complete, status will be checked later.
    A request sent back to a client application from the Fileshare Server has not completed within the expected time period. This message indicates that the Fileshare Server will continue processing requests from other client applications normally and will check the status of this request at a later time.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS151-I to FS200-W
Messages from FS201-S to FS252-S


FS101-I text -- parameter has been accepted.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS103-I The log filename has been added to the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS104-I The log file cannot be found, creating a new recovery log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS105-W The disk free space for the log file is below acceptable limits.

The amount of disk space remaining is calculated as a percentage of the total size of the disk where the log file is being written. The default is for this warning to be displayed when less than 5 percent of the total disk space remains free. This percentage can be changed using the /p option when entering the log filename into the database reference file using the Database Reference File Maintenance Utility.

Note:

If disk space is not cleared, the drive where the recovery log file is located will become so full as to make rollforward recovery logging impossible.

Resolution:

Clear disk space on the drive where the recovery log file is being written so that the Fileshare Server can continue logging the updates being performed.

Alternatively, if the amount of free disk space is becoming very low, the Fileshare Server should be shut down and the recovery log file backed up and deleted before starting the Fileshare Server again.

Parent topic: Messages from FS101-I to FS149-I


FS106-I filename - added to database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS107-I filename - removed from the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS108-I Processing the files specified in the database reference file.

  • The Database Reference File Maintenance Utility searches through the list of files to check the integrity of each one and also determine the current sequence numbers that are in use (if any)
  • The Fileshare Server scans the names in the database reference file in order to determine the processing to be done on each file
  • The Rollforward Recovery Utility searches through the list of files to check the integrity of each file and the sequence number in the header of each one

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS109-W The file filename does not exist.

Resolution:

If the file should exist, ensure that the filename and the path specified are correct and that the Fileshare Server is able to open the file with read-write access. Also ensure that the file is not open by another process as the Fileshare system requires exclusive access to the file.

If the file should not exist (for example, it is expected that it will be created by an application program), then this warning can be ignored.

Parent topic: Messages from FS101-I to FS149-I


FS110-I filename - OK.

Resolution:

No action is required as this message is informational.

Parent topic: Messages from FS101-I to FS149-I


FS111-W Files are still open. Continue to close down the Fileshare Server (Y/N) ?

Resolution:

At the prompt enter Y or N depending on whether the Fileshare Server is to be closed down or not.

Parent topic: Messages from FS101-I to FS149-I


FS114-W Waiting for the old log file to be removed.

Resolution:

The current log file should be backed up. The log file should then be moved so that the Fileshare Server can continue writing to the directory. If a rollforward recovery is necessary, the log files should be provided in the order that they were created to the Rollforward Recovery Utility. The Rollforward Recovery Utility will prompt for the continuation log files as they are required, if they cannot be located automatically.

Parent topic: Messages from FS101-I to FS149-I


FS118-I The database sequence number matches the sequence number in the log file, no recovery is needed.

You see this message when the Rollforward Recovery Utility has been invoked to perform a rollforward recovery. The Rollforward Recovery Utility has read the sequence numbers from the header of the files and also the last one that was written to the recovery log file. The sequence number in the headers and in the log file are the same indicating that the last updates written to the recovery log file have been applied to the files. It is therefore not necessary to perform a rollforward recovery as there are no updates in the recovery log file that have not already been applied to the files.

It is not necessary to perform the rollforward recovery.

See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity for more details.

Resolution:

No action is required

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS122-I Communications too busy on CCI SEND - retrying.

The Fileshare Server will retry the operation until the CCI protocol has been able to complete the operation.

This message could indicate that the network or network software is reaching a limit or is very busy.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS123-I Communications too busy on CCI RECEIVE - retrying.

The Fileshare Server will retry the request until valid data is returned from CCI

This message could indicate that the network or network software is reaching a limit or is very busy

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS124-I Checking the validity of the log file, please wait.

The fact that the log file does not contain a valid last record indicates that the recovery log file was not closed in a controlled manner and that the Fileshare Server which was writing to the recovery log file terminated abnormally.

See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity for more information.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS125-I Recovery possible to last valid recovery log file record.

The Rollforward Recovery Utility will apply the updates up to the point of the last valid record stored in the recovery log file.

See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity for more information.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS126-I Performing recovery, please wait.

The Rollforward Recovery Utility will now start the recovery process. The time required to perform the recovery depends on the number of updates that are logged in the recovery log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS127-S Invalid name mapping command.

See the section Filename Mapping in the chapter Advanced Operation and the section Database Reference File Maintenance in the chapter Database Integrity for more information on the /fs option.

Resolution:

If the option has been specified on the command line, include the /af option to specify the name of the replacement string value and retry the operation.

If the option is specified in a database reference file, this error indicates that the database reference file has become corrupt or has been changed without using the Database Reference File Maintenance Utility.

In this situation, it may be possible to remove the invalid entry using a normal text editor. If this is unsuccessful, discard the current database reference file and create a new one using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS101-I to FS149-I
Related information
Filename Mapping
Database Reference File Maintenance


FS128-W Fileshare Server closedown invoked by Stop Run processing.

This message should not be displayed under normal circumstances. Possible causes for this error are:

  • Closing the Fileshare Session on Windows or a kill command on UNIX. Such methods of closing the Fileshare Server should not be used as it can lead to files being corrupted and the recovery log file not being written to disk correctly.
  • The Fileshare Server has encountered an internal processing error which has caused the closedown code in the run-time system to be invoked. In this situation you should contact our technical support department to try and ascertain the cause of this error.

The Fileshare Server terminates by closing all files, rolling back any outstanding transactions, clearing all communication links with Fileshare Clients and closing the recovery log file (if in use).

Resolution:

You should try to ascertain why the Fileshare Server closed in this manner.

Parent topic: Messages from FS101-I to FS149-I


FS129-I The Fileshare Server is still active.

This message indicates that the Fileshare Server is continuing to function as normal.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
FS097
FS111


FS130-I Reading database reference file, please wait.

The amount of time required to process the database reference file depends on the amount of information contained in the file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS131-W Invalid communications mode - parameter ignored.

Resolution:

Ensure that the value specified for the communications parameter is valid.

If you do not wish to specify a communications protocol you should not use the /cm option. The Fileshare Server uses the default communications protocol for the operating system on which it is running.

Parent topic: Messages from FS101-I to FS149-I
Related information
Communications


FS132-I The Fileshare Server is running with the following communication protocol(s):

The Fileshare Client application programs can use any of the protocols listed to contact this Fileshare Server.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS133-I Processing the password file, please wait.

The password file has been successfully located and opened and is now being processed.

The time required for this operation depends on the amount of information that is stored in the password file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS134-I The password file cannot be found - creating a new password file.

The Password File Maintenance Utility will therefore try to create a new password file of the name specified.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS135-I Fileshare Server security is active.

See the chapter Security for more details about the Fileshare Server security features and how to use them.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Security


FS136-I Fileshare Server security is not active.

Logons are validated by the Fileshare Server by calling the FSSECLOG module.

See the chapter Security for more details about the Fileshare Server security features and how to use them.

See the section Password File Maintenance in the chapter Security for more information about supervisor passwords.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Security
Password File Maintenance


FS138-W The log file has been backed up and a new one has been created.

This implies that the Fileshare Server which was previously writing to this log file terminated abnormally.

Because the Fileshare Server is unable to append to the existing log file, it has been renamed and a new recovery log file has been created. This new recovery log file will be used.

Note:

This message implies that the correct sequence of regularly backing up data files and deleting recovery log files is not being performed as the Fileshare Server is being started when a recovery log file already exists.

See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Resolution:

No action is required

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging


FS139-I A matching date and time entry has been found in the log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS140-I No matching date and time entry has been found in the log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS142-W The Operating System does not permit the log file to be flushed to disk.

This message indicates that an error was returned from the operating system when it tried to flush the recovery log file to disk. This implies that the operating system does not enable application programs to force I/O buffers to be flushed to disk. Consequently, the Fileshare Server is unable to force the operating system to write the contents of the recovery log file to disk and in the event of a system failure, it is possible that not all of the contents of the recovery log file will be available when the recovery process is performed.

Resolution:

See the section Database Reference File Maintenance in the chapter Database Integrity and Rollforward Recovery for more details.

Parent topic: Messages from FS101-I to FS149-I
Related information
Database Reference File Maintenance


FS143-W The Operating System does not allow free disk space information to be obtained.

This message indicates that the call to the operating system to determine how much disk space is available has returned an error. This implies that the operating system does not enable applications to determine how much disk space is available.

Resolution:

It is the system administrator's responsibility to ensure that sufficient disk space is available, as the Fileshare Server is unable to determine the amount of free space available on the drive. If the Fileshare Server is unable to write a recovery log file because there is insufficient disk space, the Fileshare Server automatically closes down.

Parent topic: Messages from FS101-I to FS149-I


FS144-W More than one communications protocol has been specified - synchronous communications mode not active.

With this mode of communication it is only possible to start the Fileshare Server with one communications protocol.

This message indicates that the Fileshare Server is configured to use more than one communications protocol and so the synchronous communications option has been ignored.

The Fileshare Server has started, but it is not using the synchronous communications mode.

Resolution:

If the synchronous communications mode is required, make sure that the Fileshare Server is configured to use only one communications protocol.

Parent topic: Messages from FS101-I to FS149-I


FS145-W Fileshare Client disconnected, cannot contact user: text.

You see the user number and user name, if one was supplied at the time that this user logged onto the Fileshare Server.

The Fileshare Server has closed all files that this user had open and rolled back any outstanding transactions pending for this user.

The Fileshare Client application, if still active, will be returned a 9/124 error on its next I/O operation.

Resolution:

Check that the Fileshare Client application is still running. Also check for any adverse network conditions that could have forced the connection to have been dropped.

Parent topic: Messages from FS101-I to FS149-I


FS146-W Unexpected action code, action-code - discarded.

This message can indicate that the recovery log file has become corrupted in some way or that the recovery file contains invalid information.

Resolution:

As the rollforward recovery log file contains an invalid record, it is possible that not all of the record updates have been recovered from the file. After the recovery has completed the data in the files should be checked. If the problem recurs contact our technical support department.

Parent topic: Messages from FS101-I to FS149-I


FS147-I A duplicate network message was received and discarded.

Resolution:

Ensure that the latest CCIIPX modules are installed on the Fileshare Client and Fileshare Server machines.

Parent topic: Messages from FS101-I to FS149-I


FS148-I CCI return-code (function func) = code.

The message consists of a function code which indicates which CCI verb was being used at the time of the error and the return-code received from the CCI module.

The Fileshare Server calls CCI to determine details of the error that has occurred. This information is also displayed on the screen.

Resolution:

No action is required. However, the above information should indicate the cause of an error or unexpected occurrence during the Fileshare Server operation. This information should be used with any additional information contained in other messages to determine the cause of any errors.

When contacting our technical support department the above information is important and must be included with any problem report.

Parent topic: Messages from FS101-I to FS149-I


FS149-I CCI SEND not complete, status will be checked later.

Message FS228 is displayed when it is determined that the request eventually either completed or failed.

If you see this message frequently, it may be due to large record sizes taking longer to process than expected on slower network connections.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
FS228


Messages from FS151-I to FS200-W

  • FS151-I CCI message size received = text. Indicated send message size = text
    You see this message in conjunction with message FS014.
  • FS153-I The Fileshare Server name has been reregistered on the network.
    The Fileshare Server tried to register its name on the network so that Fileshare Clients can contact it. An error status was returned indicating that the Fileshare Server name was already registered on the network by a Fileshare Server which terminated abnormally. As this name is not being used by an active Fileshare Server, the name has been reregistered on the network by the Fileshare Server being started.
  • FS154-I Please enter the FSVIEW supervisor password to enable the use of CCI Trace.
    The Fileshare Server is being started and is configured to use the CCI Trace option. This option can only be used by a supervisor because it can cause a large amount of disk space to be used for storing the CCI Trace file. When starting the Fileshare Server a password file should be specified that contains a user-ID of FSVIEW.
  • FS155-I Password accepted - CCI Trace is enabled. Do you want CCI Trace active immediately? (Y/N)
    You see this message displayed after the supervisor has entered the supervisor password to enable the use of CCI Trace. The Fileshare Server has confirmed that the password entered is correct and it is now possible to use CCI Trace.
  • FS156-W Incorrect password - CCI Trace is disabled.
    You see this message after the FSVIEW supervisor has entered the supervisor password to enable the use of CCI Trace.
  • FS158-I CCI Trace activated.
    This message indicates that the Fileshare Server has enabled the CCI Trace option and all requests made to CCI are being logged in the CCI Trace file.
  • FS159-I CCI Trace switched off.
    This message indicates that the Fileshare Server has turned off the CCI Trace option and all requests made to CCI are no longer being logged in the CCI Trace file. You see this message when the CCI Trace is either:
  • FS160-I Fileshare trace activated.
    You see this message displayed by the Fileshare Server when the trace option has been activated using the F2 key. All requests received by the Fileshare Server will be shown, with the operation code being requested, the name of the user performing the request and some additional information depending on the operation being performed. The result of the operation (including the file status) that is returned to the Fileshare Client is also shown.
  • FS161-I Fileshare trace switched off.
    You see this message displayed by the Fileshare Server when the trace option has been toggled off using the F2 key. The Fileshare Server no longer displays requests received or information about the data being returned to the Fileshare Clients. The Fileshare Server also is no longer writing to the trace file fsscreen.lst if the trace file option was specified when the Fileshare Server was started.
  • FS163-I Input useropcode [filename-1] [ filename-2].
    You see this message when the Fileshare Server trace option is activated and a request has been received by the Fileshare Server. The information displayed is as follows:
  • FS170-I Input- Logon.
    You see this message when the Fileshare Server trace option is activated and a logon request has been received by the Fileshare Server. The Fileshare Server will process the logon request and the result of the request will also be displayed. A logon request is always the first operation performed by a new Fileshare Client connecting to this Fileshare Server.
  • FS171-I Input- Logoff user.
    You see this message when the Fileshare Server trace option is activated and a log off request has been received by the Fileshare Server. If the Fileshare Client supplied a user name when it logged onto this Fileshare Server, the user name is displayed here if Fileshare Security is active. If no user name was supplied, then the user number is displayed.
  • FS172-I Input- Find File userfilename.
    You see this message when the trace option is activated and a Find File request has been received by the Fileshare Server from a Fileshare Client when a program tries to open a file. The Fileshare Server that should process the file has not been explicitly defined and more than one default Fileshare Server is configured.
  • FS173-I Output- userstatus.
    You see this message when the Fileshare Server trace option is activated and a request has been processed by the Fileshare Server and the result sent back to the Fileshare Client
  • FS176-W There is no backup directory specified in the database reference file.
    You tried to erase a backup directory entry from the database reference file but the database reference file does not contain a backup directory entry
  • FS177-S The backup directory specified cannot be found in the database reference file.
    You tried unsuccessfully to erase a backup directory-name from the database reference file. This is because the backup directory-name specified is not the same as the backup directory-name in the database reference file.
  • FS178-I The backup directory has been added to the database reference file.
    The Database Reference File Maintenance Utility has been invoked to add a backup directory-name to the database reference file and the operation has completed successfully. The database reference file now contains the name of the backup directory specified.
  • FS179-S A backup directory is already specified in the database reference file.
    You tried to add the name of the backup directory to the database reference file. However such an entry already exists in the database reference file which can only contain one recovery log file backup directory-name.
  • FS180-W The log filename specified has an extension. The name of the log file has been changed to "filename".
    The Database Reference File Maintenance Utility has been invoked to add the name of the recovery log file to the database reference file. The name of the log file specified contained an extension and this has been removed. The extension is removed to enable the Fileshare Server to automatically backup the recovery log file when necessary. The name of the log file added to the database reference file is shown.
  • FS182-W Output- Access Denied
    You see this message when the Fileshare Server trace option is activated and a logon request was received by the Fileshare Server from the Fileshare Client. This logon request has been denied, either because:
  • FS188-W Fileshare Server database reference file installation completed with errors.
    The Database Reference File Maintenance Utility has been used to update the contents of the database reference file. However, an error was found when parsing the command line passed to the utility or when processing the information stored in the database reference file.
  • FS189-W The backup directory does not exist.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS190-W The backup directory specifies the name of an existing file.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS191-W An error occurred accessing the backup directory.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS192-S More than one log file exists in the log file directory.
    You see this message when the Fileshare Server is starting up. The Fileshare Server has searched the directory where the recovery log file is to be written and has determined that more than one recovery log file exists in the directory. The Fileshare Server is unable to determine which of these recovery log files is a valid one and hence which one it can append data to.
  • FS193-S Unable to open the log file.
    The Fileshare Server has determined that a recovery log file exists in the directory where the recovery log file is specified but an error was returned when the Fileshare Server tried to open it.
  • FS194-I The log file "filename-1" has been backed up successfully to "filename-2".
    This message indicates that the Fileshare Server has successfully backed up the recovery log file. The backup operation was performed either as a request from FSVIEW or FSMGR or because the current recovery log file cannot be appended to and has been automatically backed up when the Fileshare Server has started. filename-1 is the name of the log file that has been backed up. filename-2 is the name of the file that the log file has been backed up to.
  • FS195-I The Fileshare Server is using the log file "filename".
    The Fileshare Server has successfully opened (and created if necessary) the recovery log file indicated and is writing recovery records to this log file.
  • FS196-W Unable to create the log file "filename".
    The Fileshare Server tried to create the recovery log file indicated, but was unable to do so.
  • FS197-S Unable to create the log file "filename".
    The Fileshare Server tried to create the recovery log file indicated, but was unable to do so.
  • FS198-W The attempt to backup the log file failed because the backup file "filename" already exists.
    The Fileshare Server was unable to backup the recovery log file to the directory and name specified because a file of that name already exists.
  • FS199-S The attempt to backup the log file failed because the backup file "filename" already exists.
    The Fileshare Server was unable to backup the recovery log file to the directory and name specified because a file of that name already exists.
  • FS200-W The attempt to backup the log file to "filename" failed.
    The Fileshare Server tried to copy the recovery log file to the directory and name specified but encountered an error when doing so. Possible causes are that the directory is full or that a disk I/O error occurred during the copying process.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS201-S to FS252-S


FS151-I CCI message size received = text. Indicated send message size = text

The information sent from the Fileshare Client to the Fileshare Server includes a check on the amount of information that is being sent. This error states that the amount of data received by the Fileshare Server is not the same as the amount sent by the Fileshare Client.

This message shows the amount of data that has been received by the Fileshare Server and also the amount of data that was sent by the Fileshare Client.

The Fileshare Server has ignored the data sent from the Fileshare Client.

Resolution:

If using the NETBIOS protocol, ensure that it is installed correctly, configured and operational.

It is highly likely that the Fileshare Client appears to have stopped because the Fileshare Server has not sent any reply back. Depending on the CCI protocol being used, a time-out occurs in approximately two minutes and a 9/124 status is returned to the application program.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS014-W


FS153-I The Fileshare Server name has been reregistered on the network.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS154-I Please enter the FSVIEW supervisor password to enable the use of CCI Trace.

See the section Password File Maintenance in the chapter Security for more information.

See also the messages FS155 and FS156.

Resolution:

At this prompt enter the supervisor password that corresponds to the entry in the password file for the user-ID of FSVIEW

Parent topic: Messages from FS151-I to FS200-W
Related information
Password File Maintenance
FS155
FS156


FS155-I Password accepted - CCI Trace is enabled. Do you want CCI Trace active immediately? (Y/N)

This prompt is to determine if the Fileshare Server is to trace communication requests immediately and include all of the CCI initialization requests made by the Fileshare Server.

Resolution:

Responding Y enables the Fileshare Server to start using CCI Trace immediately and causes all CCI initialization requests to be traced to the CCI Trace file. The CCI Trace remains operational until toggled off using the F3 key.

Entering any other response apart from Y does not enable CCI trace immediately. However, CCI trace can be toggled on at a later time using the F3 key.

See also the messages FS154 and FS156.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS154
FS156


FS156-W Incorrect password - CCI Trace is disabled.

The Fileshare Server has determined that the password entered is incorrect and has consequently disabled the use of the CCI Trace feature.

Resolution:

If CCI Trace is required then the Fileshare Server should be brought down using the Esc key sequence. Ensure that when starting the Fileshare Server the /pf option is used to specify a password file that contains a password for the user-ID FSVIEW. When prompted to enter the supervisor password the password for the FSVIEW user-ID should be entered.

If CCI Trace is not required then no action is required as the Fileshare Server has started and the CCI Trace feature is not enabled. However, to prevent this message in future, the Fileshare Server should be reconfigured not to use CCI Trace.

Parent topic: Messages from FS151-I to FS200-W


FS158-I CCI Trace activated.

You see this message when either CCI Trace is made active on start-up, or is toggled on using the F3 key while the Fileshare Server is operational.

Note:

The CCI Trace file can become very large. If no disk space remains to enable the CCI Trace file to be written, no errors are reported and the tracing of CCI requests is suspended.

Resolution:

No action is required

Parent topic: Messages from FS151-I to FS200-W


FS159-I CCI Trace switched off.

  • Not made active immediately on the Fileshare Server starting up (see the message FS155)

    or

  • Toggled off using the F3 key while the Fileshare Server is operational

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS155


FS160-I Fileshare trace activated.

If the trace to a file option was specified when the Fileshare Server was started then the information displayed on the screen is also written to a file called fsscreen.lst.

The trace option can be toggled off using the F2 key.

See also message FS161.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS161


FS161-I Fileshare trace switched off.

The trace option can be toggled on using the F2 key.

See also message FS160.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS160


FS163-I Input useropcode [filename-1] [ filename-2].

user | If the Fileshare Client supplied a user name when it logged onto this Fileshare Server then the user name is displayed here if Fileshare Security is active. If no user name was supplied, the user number is displayed. The user number is generated when the Fileshare Client logs onto this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2, etc.
opcode | This is an indication of the type of action requested by the Fileshare Client. Most normal operations appear as an action-code. If a byte stream operation is being performed, the name of the operation is displayed. For COMMIT operations, an indication is given if the COMMIT is part of a prepare, confirm or abort stage of the transaction processing (if the transaction spans more than one Fileshare Server).
filename-1 | If the operation being performed is specific to a file then the name of the file is displayed here
filename-2 | If the operation being performed is specific to a file and requests to the file are being mapped to a different file using the alternate filename mapping option, the actual name of the file being processed is displayed here

The information displayed will also be written to a file called fsscreen.lst if the trace file option was specified when the Fileshare Server was started.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS170-I Input- Logon.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS171-I Input- Logoff user.

The user number is generated when the Fileshare Client logs onto this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2.

A logoff request is the last operation performed by a Fileshare Client when the Fileshare Client application program terminates.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS172-I Input- Find File userfilename.

The Fileshare Client is in the process of polling each default Fileshare Server to determine if that Fileshare Server should process requests for this file.

The information displayed is as follows:

user | If the Fileshare Client supplied a user name when it logged onto this Fileshare Server, the user name is displayed here if Fileshare Server security is active. If no user name was supplied, then the user number is displayed. The user number is generated when the Fileshare Client logs on to this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2.
filename | The name of the file that the Fileshare Client is trying to open

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS173-I Output- userstatus.

The information displayed is as follows:

user | If the Fileshare Client supplied a user name when it logged onto this Fileshare Server then the user name is displayed here. If no user name was supplied, the user number is displayed. The user number is generated when the Fileshare Client logs onto this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2.
status | The error status generated from the result of the requested operation. For normal file I/O operations this is the same format as standard file I/O statuses. Note that this status may not be the status that is returned to the application program. The Fileshare Client uses the status displayed here to do any status conversion necessary before returning the status to the application program.

For byte-stream I/O calls and other functions, the code returned to the Fileshare Client is displayed.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS176-W There is no backup directory specified in the database reference file.

Resolution:

No action is necessary (as the erase operation is not required because there is no backup directory name specified in the database reference file).

Parent topic: Messages from FS151-I to FS200-W


FS177-S The backup directory specified cannot be found in the database reference file.

Resolution:

Specify the correct backup directory-name when trying to erase the entry from the database reference file. If the name specified in the database reference file is not known then the current database reference file should be discarded and a new one created using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS151-I to FS200-W


FS178-I The backup directory has been added to the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS179-S A backup directory is already specified in the database reference file.

Resolution:

Remove the current backup directory-name from the database reference file using the Database Reference File Maintenance Utility (/e erase option) and then add the name of the new backup directory using the same utility.

Parent topic: Messages from FS151-I to FS200-W


FS180-W The log filename specified has an extension. The name of the log file has been changed to "filename".

Resolution:

No action is required (as the Fileshare Server has removed the extension and added the altered name to the database reference file). To avoid this message in the future, do not use a filename with an extension when adding a recovery log filename to the database reference file.

Parent topic: Messages from FS151-I to FS200-W


FS182-W Output- Access Denied

  • Password security is active and an incorrect password or user-ID was supplied.

    or

  • Password security is not active and the logon validation by the module FSSECLOG failed.

Resolution:

If the password file security option is:

  • Active, ensure that the application program has supplied a valid user-ID and password to the Fileshare Client. Also ensure that the user-ID and password are in the password file that was specified when the Fileshare Server was started.
  • Inactive, the logon has been denied by the FSSECLOG module. This module supplied with the Fileshare Server enables any Fileshare Client to log on to the Fileshare Server. This therefore suggests that the logon has been denied by a user-supplied FSSECLOG module and the appropriate action should be taken.

See the chapter Security for more information.

Parent topic: Messages from FS151-I to FS200-W
Related information
Security


FS188-W Fileshare Server database reference file installation completed with errors.

The database reference file has been left unaltered as the operation was unsuccessful.

Resolution:

Ensure that the command line specified for the Database Reference File Maintenance Utility is correct. Other messages displayed by the Database Reference File Maintenance Utility indicate which error has occurred.

For information on valid parameters, see the section Database Reference File Maintenance in the chapter Database Integrity .

Parent topic: Messages from FS151-I to FS200-W
Related information
Database Reference File Maintenance


FS189-W The backup directory does not exist.

This message indicates that the directory specified does not exist.

The backup directory-name has been added to the database reference file.

Resolution:

Check that the directory-name and path specified are correct. If they are not correct, the entry should be removed from the database reference file (using the /e (erase) option and the Database Reference File Maintenance Utility) and the correct entry added to the database reference file using the same utility.

If the path and directory-name are correct, ensure that the directory is created or made available to the Fileshare Server before starting the Fileshare Server, so that the automatic backup can take place. If the directory does not exist, the Fileshare Server fails when trying to back up the recovery log file or the data files automatically when required to do so.

Parent topic: Messages from FS151-I to FS200-W


FS190-W The backup directory specifies the name of an existing file.

This message indicates that the directory specified is the name of a file and not the name of a directory.

The backup directory-name has been added to the database reference file.

Resolution:

Check that the directory-name and path specified are correct. If they are not correct, the entry should be removed from the database reference file (using the /e (erase) option and the Database Reference File Maintenance Utility) and the correct entry added to the database reference file using the same utility.

If the path and directory-name are correct then before starting the Fileshare Server, ensure that a directory of the name specified is created or made available to the Fileshare Server so that the automatic backup can take place. The file of this name should be removed.

If the directory does not exist, the Fileshare Server fails when trying to back up the data files or the recovery log file automatically when required to do so.

Parent topic: Messages from FS151-I to FS200-W


FS191-W An error occurred accessing the backup directory.

This message indicates that the Database Reference File Maintenance Utility received an unexpected error when verifying that the directory exists.

See also messages FS189-W and FS190-W.

The backup directory-name has been added to the database reference file.

Resolution:

If the path and directory-name are correct, ensure that a directory of the name specified is created or made available to the Fileshare Server before starting the Fileshare Server, so that the automatic backup can take place.

If the directory does not exist or cannot be accessed, the Fileshare Server fails when trying to back up the data files or the recovery log file automatically when required to do so.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS189-W
FS190-W


FS192-S More than one log file exists in the log file directory.

Recovery log files have an extension which start with L. This message indicates that the correct procedures for backing up data files and deleting recovery log files are not being followed.

The Fileshare Server will not start up until this problem is resolved.

Resolution:

Ensure that the correct recovery log file is in the directory where the log file is to be written. Alternatively ensure that the directory does not contain any recovery log file so that the Fileshare Server creates a new one when it starts up.

Make sure that the correct procedures for using rollforward recovery logging are used. See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity.

Parent topic: Messages from FS151-I to FS200-W
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS193-S Unable to open the log file.

This error indicates that the Fileshare Server does not have the correct permissions to access the file or that the recovery log file is in use by another process. The Fileshare Server requires read and write access to the recovery log file and will try to open the file with exclusive access.

This message can occur:

  • When the Fileshare Server is starting up, in which case the Fileshare Server will not start and the problem should be corrected before the Fileshare Server is started again
  • When the Fileshare Server is in the process of backing up the recovery log file. The backup of the log file failed and the Fileshare Server has tried to use the original recovery log file. However, the opening of the recovery log file failed. In this situation, the logging of updates is suspended.

Resolution:

Ensure that the Fileshare Server has read and write access permissions to the recovery log file and that the file is not in use by another process.

Parent topic: Messages from FS151-I to FS200-W


FS194-I The log file "filename-1" has been backed up successfully to "filename-2".

If a recovery log file backup directory has been specified, then the backed-up recovery log file is in the backup directory.

If the log file was backed up when the Fileshare Server started, this indicates that the old recovery log file was not closed in a controlled manner. Not all of the updates in the old log file can be applied to the data files if a rollforward recovery becomes necessary. You are advised to close down the Fileshare Server and perform a rollforward recovery with the old recovery log file to restore the data files to a consistent state. The recovery log file should then be discarded and a new one will be created when the Fileshare Server is restarted.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS195-I The Fileshare Server is using the log file "filename".

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS196-W Unable to create the log file "filename".

The Fileshare Server was unable to create the new recovery log file after backing up the one that was in use. As the Fileshare Server is already operational, it does not close down. The Fileshare Server tries to re-open the old recovery log file and tries to continue writing recovery records to it. This message indicates that overall, the backing up of the recovery log file failed. The Fileshare Server is still operational.

Resolution:

Ensure that the log filename contains a valid directory and filename. The Fileshare Server requires read-write access to the log file and permissions to create the file if necessary. Ensure that, if the file of this name already exists, it is not being used by another process.

Parent topic: Messages from FS151-I to FS200-W


FS197-S Unable to create the log file "filename".

The Fileshare Server was unable to create the recovery log file when it was starting up and so will not start. The problem should be rectified before trying to start the Fileshare Server again.

Resolution:

Ensure that the log filename contains a valid directory and filename. The Fileshare Server requires read-write access to the log file and permissions to create the file if necessary. Ensure that, if the file of this name already exists, it is not being used by another process.

Parent topic: Messages from FS151-I to FS200-W


FS198-W The attempt to backup the log file failed because the backup file "filename" already exists.

The Fileshare Server was unable to backup the log file that is currently in use. As the Fileshare Server is already operational, it cannot close down. The Fileshare Server tries to re-open the old recovery log file and tries to continue writing recovery records to it. This message indicates that overall, the backing up of the recovery log file failed. The Fileshare Server is still operational.

Resolution:

Remove the filename indicated so that the recovery log file can be automatically backed up.

This message can indicate that the correct sequence of backing up data files and removing recovery log files is not being followed.

See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Parent topic: Messages from FS151-I to FS200-W
Related information
Rollforward Recovery Logging


FS199-S The attempt to backup the log file failed because the backup file "filename" already exists.

The Fileshare Server was unable to back up the log file to which it cannot append. The Fileshare Server is unable to append to the current recovery log file and is also unable to back it up and will therefore not start. The problem should be rectified before trying to start the Fileshare Server again.

Resolution:

Remove the filename indicated so that the recovery log file can be automatically backed up.

This message can indicate that you are not following the correct sequence of backing up data files and removing recovery log files.

See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Parent topic: Messages from FS151-I to FS200-W
Related information
Rollforward Recovery Logging


FS200-W The attempt to backup the log file to "filename" failed.

The Fileshare Server was unable to back up the log file that is currently in use. As the Fileshare Server is already operational, it cannot close down. The Fileshare Server will try to re-open the old recovery log file and continue to write recovery records to that. This message indicates that overall, the backing up of the recovery log file failed. The Fileshare Server is still operational.

Resolution:

Ensure that the filename and directory of the backup file are correct. Also ensure that there is enough disk space in the backup directory for the recovery log file to be copied.

If you are trying to start the Fileshare Server, this message can indicate that you are not following the correct sequence of backing up data files and removing recovery log files. See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Parent topic: Messages from FS151-I to FS200-W
Related information
Rollforward Recovery Logging


Messages from FS201-S to FS252-S

  • FS201-S The attempt to backup the log file to "filename" failed.
    The Fileshare Server failed to copy the recovery log file to the directory and name specified. Possible causes are that the directory is full or that a disk I/O error occurred during the copying process.
  • FS202-I The Fileshare Server will continue logging to the log file "filename".
    The Fileshare Server failed to backup the recovery log file as part of an FSView or FSMgr operation and is trying to continue logging to the old recovery log file specified.
  • FS203-I The Fileshare Server is appending to the log file "filename".
    The Fileshare Server has found a valid recovery log file to which it is able to append data.
  • FS204-W The Fileshare Server is unable to log to the log file "filename". Rollforward recovery logging is disabled.
    The Fileshare Server has failed to back up the recovery log file as part of an FSView or FSMgr operation. Consequently, the Fileshare Server does not have a valid recovery log file into which it can write records.
  • FS205-W Unable to remove the old recovery log file "filename".
    The Fileshare Server has successfully backed-up the recovery log file as part of an FSView or FSMgr operation. However, deleting the old recovery log file returned an unexpected error. The Fileshare Server tries to create the new recovery log file.
  • FS206-S There is more than one starter log file. The Recovery Utility is unable to determine which one to use.
    You see this message when the Rollforward Recovery Utility has determined that there is more than one starter recovery log file. When the Fileshare Server starts, it creates a starter recovery log file and a new log file.
  • FS207-I There is no starter log file in the log file directory.
    The Rollforward Recovery Utility has been invoked and has scanned all of the recovery log files in the current directory. It has not found a starter log file, so the recovery cannot start using a log file in the recovery log file directory.
  • FS208-S There is no starter log file in the backup directory.
    The Rollforward Recovery Utility has been invoked and has scanned all of the recovery log files in the backup directory. No starter log file was found and so the recovery cannot commence.
  • FS209-I A starter log file has been located in the backup directory.
    The Rollforward Recovery Utility has not found a starter log file in the recovery log file folder, but one was located in the backup folder. The Rollforward Recovery Utility can start the rollforward recovery.
  • FS210-S There is more than one starter log file in the backup directory.
    The Rollforward Recovery Utility has scanned through all of the recovery log files that are in the backup directory and has determined that there is more than one starter recovery log file.
  • FS211-S An error occurred checking the header on the log file "filename".
    The Rollforward Recovery Utility found the log file indicated but was unable to open it. This message can also indicate that the file was opened successfully but the Rollforward Recovery Utility could not read the first record in the file.
  • FS212-I The Rollforward Recovery Utility is processing the log file "filename".
    The Rollforward Recovery Utility has successfully opened the starter or continuation recovery log file indicated and is processing the update information contained in it
  • FS213-W Unable to locate the continuation log file "filename" in the log file directory.
    The Rollforward Recovery Utility has processed the first recovery log file.
  • FS214-I Searching for a backed up log file in the log file directory.
    The Rollforward Recovery Utility cannot find the required recovery log file in the current log file directory. It is now searching for a backed-up copy of the required recovery log file in the log file directory.
  • FS215-I Searching for a backed up log file in the backup directory.
    The Rollforward Recovery Utility cannot find the required recovery log file in the current log file directory. It is now searching for a backed-up copy of the required recovery log file in the backup directory
  • FS216-I No backed up starter log file can be found in the log file directory.
    The Rollforward Recovery Utility has searched unsuccessfully for a backed-up starter recovery log file in the log file current directory
  • FS217-I No backed up starter log file can be found in the backup directory.
    The Rollforward Recovery Utility has searched unsuccessfully for a backed-up starter recovery log file in the backup directory
  • FS218-I No backed up continuation log file can be found in the log file directory.
    The Rollforward Recovery Utility has searched unsuccessfully for a backed-up continuation recovery log file in the current log file directory
  • FS219-I No backed up continuation log file can be found in the backup directory.
    The Rollforward Recovery Utility has searched unsuccessfully for a backed-up continuation recovery log file in the backup folder
  • FS220-I A backed up starter log file has been found in the log file directory.
    The Rollforward Recovery Utility has found a backed-up starter log file in the current log file recovery directory.
  • FS221-I A backed up starter log file has been found in the backup directory.
    The Rollforward Recovery Utility has found a backed-up starter log file in the backup directory.
  • FS222-I A backed up continuation log file has been found in the log file directory.
    The Rollforward Recovery Utility has found a backed-up continuation log file in the current recovery log file directory.
  • FS223-I A backed up continuation log file has been found in the backup directory.
    The Rollforward Recovery Utility has found a backed-up continuation log file in the backup directory.
  • FS224-S The log file directory contains more than one backed up starter log file.
    The current log file directory contains more than one backed-up starter log file and so the Rollforward Recovery Utility is unable to determine which one is the correct one to use.
  • FS225-S The backup directory contains more than one backed up starter log file.
    The Rollforward Recovery Utility has searched the backup directory for a backed-up starter log file. The backup directory contains more than one backed-up starter log file and so cannot determine which one is the correct one to use.
  • FS227-W Failure to set Fileshare Server's access rights.
    You only see this message displayed by the Fileshare NLM.
  • FS228-I CCI SEND status checked.
    A request sent back from the Fileshare Server to a client application, which previously had not completed within the expected time period, has now either failed or completed successfully.
  • FS229-I Unrecognized CCI session ID - could not disconnect user.
    The Fileshare Server tried to disconnect a Fileshare Client. However, the CCI session ID is invalid which means that the Fileshare Server cannot find details of this Fileshare Client.
  • FS230-I User : user-IDuser-name
    You see this message when the Fileshare Server has received an error from a CCI module following a communications request. The error message indicates a problem has occurred in contacting a specific Fileshare Client.
  • FS231-S The parameter "nnn" is not numeric.
    You see this message when the Fileshare Server is parsing the information supplied on the command line or in the Fileshare Server configuration file. The option specified requires a value which is numeric, however the value specified is not numeric and so that parameter cannot be processed.
  • FS232-I Date : date.
    This information is written to a Fileshare Server trace file (if one is in use) when the Fileshare Server starts up. It is also written to the Fileshare Server trace file when the date of the previous message written to the trace file is different to the current date and a new message is being written to the trace file.
  • FS233-W Unable to set the maximum amount of dynamic memory to the limit specified.
    This message is only displayed by the Fileshare NLM.
  • FS234-W The parameter "text " specifies a memory limit below the minimum of 6 Mbytes allowed.
    This message is only displayed by the Fileshare NLM.
  • FS235-W Failure to allocate memory for incomplete CCI SEND processing.
    The Fileshare Server has tried to allocate some memory in order to process CCI requests to multiple Fileshare Client sessions simultaneously, but there is insufficient free memory available. Consequently, the Fileshare Server may not be able to process communications requests correctly.
  • FS236-I The log file name has been removed from the database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully removed the log file name from the database reference file
  • FS237-S The next log file to use filename already exists, unable to back up current log file.
    The Fileshare Server was unable to create the recovery log file because a file of the same name already exists
  • FS237-W The next log file to use filename already exists, unable to back up current log file.
    The Fileshare Server has tried to back up the current log file but was unable to create a new recovery log file because a file of that name already exists. The Fileshare Server will try to re-open the old log file and continue to write records to it.
  • FS238-I Terminating communications with this user.
    You see this message, together with FS015-W, when the network connection with an unknown Fileshare Client terminates
  • FS239-I Output - user Record locked. Retry operation.
    You see this message when tracing is enabled and an I/O operation returns a status of record locked. The user application making the request is compiled with the RETRYLOCK directive which specifies that the request is automatically retried when a status of record locked is returned. The Fileshare Server sends this message to the Fileshare Client requesting that it retries the operation.
  • FS240-I Output - user File locked. Retry operation.
    You see this message when tracing is enabled and an I/O operation returns a status of file locked. The user application making the request has the Callable File Handler RETRYOPEN option set which specifies that the open request is automatically retried when a status of file locked is returned. The Fileshare Server sends this message to the Fileshare Client requesting that it retries the operation.
  • FS241-I Output - user Insufficient log file disk space. Retry operation.
    You see this message when tracing is enabled and the amount of free disk space available to the Fileshare Server to log updates in the log file is below 200 Kbytes. See the messages FS030-S and FS114-W for further information.
  • FS243-S Failure backing up the file filename1 to filename2.
    During an automatic backup of the data files, an error has occurred while copying the file specified by filename1 to the destination specified by filename2
  • FS244-S Failure restoring the backed up file filename1 to filename2.
    An error has occurred while copying the file specified by filename1 to the destination specified by filename2 during an automatic restoration of the data files before running the Recovery Utility
  • FS245-S Failure deleting the log file filename.
    A failure occurred when Fileshare tried to delete the redundant log file, filename.
  • FS246-I Backing up database files to directory backup directory. Please wait.
    The data files listed in the database reference file are being copied to the directory specified by the /backup option
  • FS247-I Restoring database files from directory backup directory. Please wait.
    The data files listed in the database reference file are being copied from the directory specified by the /backup option to their correct locations in preparation for a Fileshare Recovery
  • FS248-I Commencing automatic Fileshare Recovery.
    This message indicates that the Fileshare Recovery Utility has been automatically invoked because the Fileshare Server has detected that the previous server session did not close down successfully
  • FS249-I Restarting Fileshare Server.
    This message indicates that the automatic Fileshare Recovery has completed successfully and that the Fileshare Server is restarting
  • FS250-I Deleting all unwanted log files.
    This message indicates that Fileshare is deleting redundant log files before re-starting the Fileshare Server when a new log file is created
  • FS251-S Logging must be activated for all files when specifying a backup directory.
    You have specified that update logging is to be switched off for one of the files named in the database reference file but have also specified a backup directory-name. You cannot do this because Fileshare automatically backs up (and restores where necessary) all the files listed in the database reference file, in order to keep them synchronized with the log file, when a backup directory is specified. If logging is not active for all files, Fileshare cannot guarantee that it can restore and recover the correct versions of these files.
  • FS252-S Failure deleting the file filename.
    An error occurred while deleting the file filename during an automatic backup or restoration of the data files
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W


FS201-S The attempt to backup the log file to "filename" failed.

The Fileshare Server is unable to append to the current recovery log file and is also unable to back it up and so will not start. You should rectify the problem before trying to re-start the Fileshare Server.

Resolution:

Ensure that the filename and directory of the backup file are correct. Also ensure that there is enough disk space in the backup directory for the recovery log file to be copied.

If you are trying to start the Fileshare Server, this message can indicate that you are not following the correct sequence of backing up data files and removing recovery log files. See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS202-I The Fileshare Server will continue logging to the log file "filename".

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS203-I The Fileshare Server is appending to the log file "filename".

This message indicates that you are not following the recommended sequence of backing up data and removing recovery log files. A recovery log file already existed when the Fileshare Server started.

See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Resolution:

No action is required

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS204-W The Fileshare Server is unable to log to the log file "filename". Rollforward recovery logging is disabled.

Rollforward recovery logging has been suspended.

Resolution:

Terminate the Fileshare Client applications and shut down the Fileshare Server. Then back up the data files, remove the recovery log file and restart the Fileshare Server to create a new recovery log file.

Parent topic: Messages from FS201-S to FS252-S


FS205-W Unable to remove the old recovery log file "filename".

Resolution:

Ensure that the Fileshare Server has the correct permissions to enable it to delete the old recovery log file. Remove the old recovery log file manually if the backup operation has succeeded. This releases more disk space for recovery logging to take place.

Parent topic: Messages from FS201-S to FS252-S


FS206-S There is more than one starter log file. The Recovery Utility is unable to determine which one to use.

Thus, if the Fileshare Server:

  • Starts and there is no recovery log file available, it creates one
  • Automatically backs up the recovery log file, it backs up the starter recovery log file and creates a continuation recovery log file
  • Performs another back up, it backs up the continuation recovery log file and creates another continuation recovery log file

A rollforward recovery can only proceed when there is only one starter recovery log file to use.

Resolution:

Ensure that the correct recovery log files are in place and then try to re-run the rollforward recovery process.

This message indicates that you are not following the correct sequence of backing up data files and removing recovery log files. See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS207-I There is no starter log file in the log file directory.

The Fileshare Server now searches for a starter recovery log file that has been backed up to the recovery log file backup directory.

Resolution:

If no starter recovery log file is found in the recovery log file backup directory, it is not possible for the rollforward recovery to be performed. Place the correct starter recovery log file in the recovery log file directory and try to re-run the rollforward recovery.

Parent topic: Messages from FS201-S to FS252-S


FS208-S There is no starter log file in the backup directory.

Resolution:

Place the correct starter recovery log file in the recovery log file directory and invoke the Rollforward Recovery Utility again to perform rollforward recovery.

Parent topic: Messages from FS201-S to FS252-S


FS209-I A starter log file has been located in the backup directory.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS210-S There is more than one starter log file in the backup directory.

A rollforward recovery can only start when there is only one starter recovery log file to use.

See the section Rollforward Recovery Logging in the chapter Database Integrity for more information.

Resolution:

Ensure that the correct recovery log files are in place and then re-try the rollforward recovery process.

This message indicates that you are not following the recommended sequence of backing up data files and removing recovery log files.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS211-S An error occurred checking the header on the log file "filename".

Resolution:

Ensure that the Rollforward Recovery Utility has read and write access to the file indicated. Also ensure that the utility is able to open the file exclusively and that it is not currently in use by another process.

Parent topic: Messages from FS201-S to FS252-S


FS212-I The Rollforward Recovery Utility is processing the log file "filename".

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS213-W Unable to locate the continuation log file "filename" in the log file directory.

The marker at the end of the recovery log file indicates that there is an additional recovery log file to be processed. This message indicates that the Rollforward Recovery Utility cannot find the next recovery log file in the same directory as the previous recovery log file.

The Rollforward Recovery Utility tries to find the next recovery log file in the backup directory if one has been specified.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS214-I Searching for a backed up log file in the log file directory.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS215-I Searching for a backed up log file in the backup directory.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS216-I No backed up starter log file can be found in the log file directory.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS217-I No backed up starter log file can be found in the backup directory.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS218-I No backed up continuation log file can be found in the log file directory.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS219-I No backed up continuation log file can be found in the backup directory.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS220-I A backed up starter log file has been found in the log file directory.

The Rollforward Recovery Utility will open and try to process the recovery log file that it has located.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS221-I A backed up starter log file has been found in the backup directory.

The Rollforward Recovery Utility will open and try to process the recovery log file which it has located

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS222-I A backed up continuation log file has been found in the log file directory.

The Rollforward Recovery Utility will open and try to process the recovery log file which it has located.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS223-I A backed up continuation log file has been found in the backup directory.

The Rollforward Recovery Utility will open and try to process the recovery log file which it has located.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS224-S The log file directory contains more than one backed up starter log file.

It is not possible to start the rollforward recovery process.

This message indicates that you have not followed the recommended sequence of backing up data files and removing unneeded recovery log files. See the section Rollforward Recovery Logging in the chapter Database Integrity for more information.

Resolution:

Ensure that only the correct backed-up starter recovery log file is in the log file directory. Then re-start the rollforward recovery process.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS225-S The backup directory contains more than one backed up starter log file.

It is not possible to start the rollforward recovery process.

This message indicates that you are not following the correct sequence of backing up data files and removing unneeded recovery log file. See the section Rollforward Recovery Logging in the chapter Database Integrity for more information.

Resolution:

Ensure that only the correct backed-up starter recovery log file is in the backup directory. Then re-start the rollforward recovery process.

Parent topic: Messages from FS201-S to FS252-S
Related information
Rollforward Recovery Logging


FS227-W Failure to set Fileshare Server's access rights.

The Fileshare NLM encountered an error when trying to set the Fileshare Server's access rights on the NetWare operating system.

This operation is performed after an I/O operation has been carried out for a Fileshare Client. Because this operation has failed, the Fileshare Server has assumed the access rights of that Fileshare Client.

This message indicates that the Fileshare Server's connection to the NetWare operating system is no longer valid. The Fileshare Server will try to connect with supervisor access rights to the NetWare operating system.

Resolution:

If this error persists you should contact our technical support department.

Parent topic: Messages from FS201-S to FS252-S


FS228-I CCI SEND status checked.

See also the message FS149.

A second message following this one indicates the outcome of the request in question. If this suggests frequent communications errors, there may be errors on the network or client applications may be terminating abnormally. The request completed normally if no message follows.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S
Related information
FS149


FS229-I Unrecognized CCI session ID - could not disconnect user.

A possible cause of this error is that CCI indicated that a Fileshare Client application program terminated abnormally, but the Fileshare Server is unable to locate details about the Fileshare Client which has terminated.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS230-I User : user-IDuser-name

This message provides information regarding the user-ID and the user-name (if available) of the Fileshare Client that the Fileshare Server tried to contact.

Resolution:

No action is required.

Use details contained in other messages displayed by the Fileshare Server to determine the cause of the error.

Parent topic: Messages from FS201-S to FS252-S


FS231-S The parameter "nnn" is not numeric.

Resolution:

Correct the Fileshare Server command line option or the Fileshare Server configuration file entry so that the value for the parameter indicated is numeric. Then try to re-start the Fileshare Server with the new command line or configuration file.

Parent topic: Messages from FS201-S to FS252-S


FS232-I Date : date.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS233-W Unable to set the maximum amount of dynamic memory to the limit specified.

This message indicates that the Fileshare NLM is configured to use a maximum amount of dynamically-allocated memory (using the /mm option).

The Fileshare Server was unable to set the limit of the amount of dynamically-allocated memory and therefore tries to allocate memory as required, with no upper limit.

Resolution:

The message indicates an internal Fileshare NLM failure. Please contact our technical support department.

Parent topic: Messages from FS201-S to FS252-S


FS234-W The parameter "text " specifies a memory limit below the minimum of 6 Mbytes allowed.

This message indicates that the Fileshare NLM is configured to use a maximum amount of dynamically-allocated memory (using the /mm option).

However, the amount of memory that it is configured to use is below the minimum of 6 Mbytes in which the Fileshare NLM can successfully operate. The Fileshare NLM has set the amount of dynamically-allocated memory it can use up to six megabytes.

Resolution:

Specify a different value for the /mm option so that the amount of dynamically-allocated memory that it can use is at least six megabytes

Parent topic: Messages from FS201-S to FS252-S


FS235-W Failure to allocate memory for incomplete CCI SEND processing.

Making more memory available to the Fileshare Server session after this message has been displayed will not rectify the problem with this particular request, although it might enable the Fileshare Server to allocate memory if it needs to in the future. However, the Fileshare Server process is near the limit of memory available to it which could adversely affect its operation.

See also the message FS149.

Resolution:

Make more memory available by closing other active applications on the machine where the Fileshare Server is running in order to avoid Fileshare Server memory problems in general.

Parent topic: Messages from FS201-S to FS252-S
Related information
FS149


FS236-I The log file name has been removed from the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS237-S The next log file to use filename already exists, unable to back up current log file.

Resolution:

The Fileshare Server has not started. Ensure that no file already exists with the same name as that which the Fileshare Server is trying to use for the next recovery log file. Then re-start the Fileshare Server.

Parent topic: Messages from FS201-S to FS252-S


FS237-W The next log file to use filename already exists, unable to back up current log file.

Resolution:

The Fileshare Server continues to run but the back up of the recovery log file has failed. Ensure that no file already exists with the same name as that which the Fileshare Server is trying to use for the next recovery log file.

Parent topic: Messages from FS201-S to FS252-S


FS238-I Terminating communications with this user.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S
Related information
FS015-W


FS239-I Output - user Record locked. Retry operation.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS240-I Output - user File locked. Retry operation.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS241-I Output - user Insufficient log file disk space. Retry operation.

Resolution:

Because the Fileshare Server can no longer guarantee that it can store updates in the log file, it has suspended operations and is waiting for the log file to be removed in order to create more disk space. While operations are suspended any requests from Fileshare Clients are rejected. Refer to messages FS030-S and FS114-W

Parent topic: Messages from FS201-S to FS252-S
Related information
FS030-S
FS114-W


FS243-S Failure backing up the file filename1 to filename2.

Resolution:

Ensure that no other process is currently accessing either filename1 or filename2 and that the Fileshare Server has sufficient access permissions to carry out this operation.

Parent topic: Messages from FS201-S to FS252-S


FS244-S Failure restoring the backed up file filename1 to filename2.

Resolution:

Ensure that no other process is currently accessing either filename1 or filename2 and that the Fileshare Server has sufficient access permissions to carry out this operation. Then re-start the Recovery Utility. If this was invoked automatically during the Fileshare Server start-up, you also need to re-start the server manually once the recovery has completed successfully.

Parent topic: Messages from FS201-S to FS252-S


FS245-S Failure deleting the log file filename.

Resolution:

Ensure that no other process is accessing the file and that the Fileshare Server has sufficient permissions to delete the log file. Fileshare cannot start up and log updates to the correct log file until the redundant log file is deleted. Once the problem is rectified you need to restart the Fileshare Server.

Parent topic: Messages from FS201-S to FS252-S


FS246-I Backing up database files to directory backup directory. Please wait.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS247-I Restoring database files from directory backup directory. Please wait.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS248-I Commencing automatic Fileshare Recovery.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS249-I Restarting Fileshare Server.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS250-I Deleting all unwanted log files.

Resolution:

No action is required.

Parent topic: Messages from FS201-S to FS252-S


FS251-S Logging must be activated for all files when specifying a backup directory.

Resolution:

If you are adding the name of a data file to the database reference file, you must add it without specifying the /o l option.

If you are adding a backup directory-name using the /backup option, you should first remove any database reference file entries for files which have logging switched off

Parent topic: Messages from FS201-S to FS252-S


FS252-S Failure deleting the file filename.

Resolution:

Ensure that no other process is accessing the file and that the Fileshare Server has sufficient permissions to delete it. You will then need to re-start the Fileshare Server or the Fileshare Recovery Utility (depending on which you were trying when the error occured).

Parent topic: Messages from FS201-S to FS252-S


Terminfo Database and Terminal Devices

Interactive COBOL applications rely heavily on sophisticated use of the terminal device for full-screen input and output, using the ACCEPT and DISPLAY statements. UNIX allows virtually any type of terminal device to be connected and provides the terminfo database as a means for handling the diversity of terminals. This chapter describes how the terminfo database is used by your COBOL system and what details need to be included in the database to enable COBOL to use particular terminal features. This section also describes the Micro Focus terminfo utilities mftic and mfinfocmp.

See Device Handling in your Program Development Guide discusses devices in general including terminal devices. This chapter describes the detailed use and configuration of terminal devices for UNIX.

  • Overview
  • Special Terminal Facilities
  • Searching Portable and System Terminfo Databases
  • Terminal Devices
  • Special Terminal Facilities
  • The Portable Terminfo Utilities mftic and mfinfocmp
Parent topic: Micro Focus COBOL Server for UNIX


Overview

The terminal is perhaps the most important and complex device that a typical COBOL program uses. It can be used in two ways:

  • For simple unformatted line input and output
  • For formatted, full screen, field input and output

For unformatted screen I/O, the COBOL system takes no special action. It simply uses the logical UNIX devices stdin, stdout and stderr (see the chapter Device Handling in your Program Development Guide) assuming that these are redirected by the operating system from or to the terminal.

For formatted screen I/O, the COBOL system has to take action at two levels: the logical level and the physical level. The Adis module translates the high-level COBOL requirements into logical, low-level, terminal-independent operations. The screen handling module translates these logical operations into the terminal-dependent physical character strings and escape sequences required by the attached terminal. The screen handling module also translates any response from the terminal into logical form and returns it to the Adis module.

To carry out the mapping between logical and physical form, the screen handling module needs to know the type of terminal that is attached, the capabilities of that terminal type and the physical format of any I/O activity. UNIX provides a standard method for providing this information; the environment variable TERM contains the name of the terminal type, and the details for that terminal type are held in a UNIX system database, known as terminfo.

  • System Terminfo
  • Portable Terminfo for COBOL
  • COBOL Screen Handling Requirements
Parent topic: Terminfo Database and Terminal Devices


System Terminfo

Your COBOL system can understand and use the standard UNIX System V terminfo format and structure, although it ignores any non-standard UNIX vendor-specific extensions. Some UNIX systems do not use the standard terminfo format and structure and in this case your COBOL system uses the alternative portable UNIX terminfo database described in this section.

The system terminfo database is located in /usr/lib/terminfo on most platforms and is available for general use by any system application, a typical example being the system editor vi. If a particular process requires use of an alternative general terminfo database, then this can be selected by specifying its location in the environment variable TERMINFO.

The terminal details are held in a terminfo database for general use by non-COBOL applications. They can be made suitable for use by COBOL applications but frequently there is a conflict. COBOL terminal I/O is generally more sophisticated than that of most UNIX applications and has more stringent minimal requirements of the terminfo database. The precise meaning of some the terminal information can be ambiguous and sometimes the terminfo database reflects an interpretation that differs from that made by the COBOL system. In addition, the terminfo database is sometimes modified to configure a non-COBOL application and so becomes unsuitable for use with a COBOL application.

Parent topic: Overview
Related information
Portable Terminfo for COBOL


Portable Terminfo for COBOL

This COBOL system supports the use of a portable UNIX terminfo database and provides one that includes details for a selection of terminals. The format follows the UNIX specification but omits the UNIX vendor-specific portions. The database can be used by COBOL applications as an adjunct or alternative to the system databases. The system COBOL terminfo database is held in the directory terminfo in the COBOL system directory $COBDIR. If a particular COBOL process requires use of an alternative COBOL terminfo database, then this can be selected by specifying its location in the environment variable COBTERMINFO.

The portable UNIX terminfo database can be maintained using the utilities mftic and mfinfocmp that are described later in this section.

Parent topic: Overview
Related information
System Terminfo


COBOL Screen Handling Requirements

When COBOL provides formatted field input and output on the terminal, it carries out some sophisticated screen handling compared to many UNIX applications. Certain terminal capabilities must be available and described in the terminfo entry referenced by TERM otherwise the run-time system gives a run-time error.

Your COBOL system tries to optimize the use of the terminal and uses some optional terminal capabilities if they are described in terminfo. Required and optional terminal terminfo details are described in this section.

Parent topic: Overview


Special Terminal Facilities

Some terminal facilities, such as Ctrl and Alt key support, are not automatically specified via the terminfo database. Other facilities such as wide terminal mode are specified via the terminfo database but are not part of the standard COBOL screen I/O. These special facilities are described later in this section.

Parent topic: Terminfo Database and Terminal Devices


Searching Portable and System Terminfo Databases

The COBOL system recognizes two types of terminfo database: the portable terminfo for COBOL and the system terminfo. When it requires details for a terminal it searches each database that is specified by the environment until it finds details for that terminal.

The COBOL system searches first for a COBOL-specific terminfo file and if that is not found it searches for a system terminfo file (see steps below). Non-COBOL utilities such as vi only search for a system terminfo file.

For a particular terminal, COBOL applications and non-COBOL applications such as vi can have different requirements for a terminfo file. Not only can different entries be required but also they can require different binary formats. COBOL might require a portable format and non-COBOL requires a system-specific format.

It is important to distinguish between general terminfo files and COBOL-specific terminfo files (examples provided with this system), to place them in separate locations and at run time to set up the environment variables COBTERMINFO (see the appendix Environment Variables) for the COBOL-specific files and TERMINFO for the system or general terminfo files as appropriate. The COBOL system then searches for a terminfo file using the following steps:

  1. If the COBTERMINFO environment variable is not set, it is considered set to $COBDIR/terminfo.
  2. If COBTERMINFO is set, it is read as a set of colon-separated paths to the terminfo database. If the required file is found on any of the paths (parsed from left to right), then it is used.
  3. If the TERMINFO environment variable is set, it is used as a path to the terminfo database. If the file is found, it is used.
  4. Use the default system terminfo database, usually/usr/lib/terminfo, as the path to the terminfo database. If the file is found here, it is used.
  5. If the file is not found, an error is returned.
Parent topic: Terminfo Database and Terminal Devices


Terminal Devices

UNIX environments support virtually any terminal type, terminal definitions being held in a system database. This database must contain enough details for the terminal being used in order that Adis can function.

Adis uses the standard input and output device interfaces for terminal I/O and so such terminal I/O can be redirected but with the restriction that you must not redirect standard input from a file unless it is a terminal device.

So, for example, the following is legal:

cobrun prog < `tty` >`tty`

(use the appropriate (`) character) whereas redirecting the input from an ordinary file or /dev/null is not legal and could result in a run time error.

  • Screen Handling Requirements
  • Essential Entries
  • Optional Entries
Parent topic: Terminfo Database and Terminal Devices


Screen Handling Requirements

The COBOL run-time system depends on a terminfo database being available and providing various terminal details to support the Adis module. The run time system regards some details as essential, and returns a run time error if they are not available. It regards all others as optional (making use of many of them and ignoring the rest). The following tables list entries in a terminfo terminal description that are recognized by the COBOL system. See your UNIX system documentation for details on the system terminfo database and how to specify terminal capabilities.

Parent topic: Terminal Devices


Essential Entries

The following entries must be present for the Micro Focus COBOL system to operate correctly. Entries marked with an asterisk (*) should be set appropriately for the type of terminal.

Entry | Mnemonic
Auto right margin * | am
Clear to end of line | el
Clear screen | clear
Clear to end of screen | ed
Cursor address (row, column) | cup
Cursor down | cud1
Cursor home | home
Cursor left | cub1
Cursor right | cuf1
Cursor up | cuu1
Eat newline glitch * | xen1
Entries for cursor keys | kcud1, kcub1, kcuf1, kcuu1
Entries for function keys f1 to f63 * | kf1 to kf63
Entries for home, next page, previous page, end, backtab, insert, delete and clear-to-end-of-field keys * | khome, knp, kpp, kend, kcbt, kich1, kdch1, kel
Exit attribute mode | sgr0
Number of columns ** | cols
Number of lines ** | lines
Xon/xoff * | xon

** The number of lines and columns will be read dynamically if using an X terminal, or can be overridden using the environment variables LINES and COLUMNS. See the appendix Environment Variables for details.

Parent topic: Terminal Devices


Optional Entries

The following entries should be used if they are required for the particular type of terminal. However, the Micro Focus COBOL system does not insist that they are present.

Entry | Mnemonic
Bell | bel
Carriage return | cr
Enter ca mode | smcup
Exit ca mode | rmcup
Keypad local | rmkx
Keypad transmit | smkx
Move safely in standout mode (if appropriate) | msgr

Some terminals must have smcup and rmcup in order to work correctly.

  • Highlighting
  • Performance Considerations
  • Wide Terminal Mode
  • Line Drawing
  • Color
Parent topic: Terminal Devices


Highlighting

For terminals that have additive attributes the following are used. Entries marked with an asterisk (*) should be set appropriately for the type of terminal:

Entry | Mnemonic
Enter blink mode * | blink
Enter bold mode * | bold
Enter dim mode * | dim
Enter reverse mode * | rev
Enter underline mode * | smul

For terminals that do not have additive attributes, the following is needed:

Entry | Mnemonic
Set attributes | sgr

Highlighting is also affected by the COBATTR environment variable. See the appendix Environment Variables for details.

Parent topic: Optional Entries


Performance Considerations

The following optional entries can be included and can improve the performance of screen displays in some situations:

Entry | Mnemonic
Parameterized cursor down | cud
Parameterized cursor left | cub
Parameterized cursor right | cuf
Parameterized cursor up | cuu

If the following entries are present, scroll regions can be used to scroll areas of the screen, which greatly speeds up such operations:

Entry | Mnemonic
Change scroll region | csr
Insert line | il1
Delete line | dl1
Parent topic: Optional Entries


Wide Terminal Mode

If you want to use wide terminal mode, you must ensure that the sequence to set the number of columns appears in one of the following entries:

Entry | Mnemonic
Initialize string 1 | is1
Initialize string 2 | is2
Initialize string 3 | is3
Reset string 1 | rs1
Reset string 2 | rs2
Reset string 3 | rs3
Parent topic: Optional Entries


Line Drawing

For terminals that have additive attributes the following are used:

Entry | Mnemonic
Enable alternate character set | enacs
Alternate character set characters | acsc
Enter alternate character set | smacs
End alternate character set | rmacs

For terminals that do not have additive attributes, the following is needed:

Entry | Mnemonic
Set attributes | sgr

If you do not specify the appropriate alternate character set characters for your terminal, or your terminal does not provide a complete set, normal ASCII characters are substituted for the missing line drawing characters.

Parent topic: Optional Entries


Color

Only the Tektronics color manipulation method can be used; for example, ANSI color terminals use the Tektronics method. The following entries are required:

Entry | Mnemonic
Number of colors | colors
Set foreground | setf
Set background | setb
Original colors | oc
Original pairs | op

Only one of oc or op needs to be specified, but it must reset to the default colors.

Check that these entries are included in your terminfo database by running the mfinfocmp utility. See Terminfo Lister (mfinfocmp) for details.

Should you require, you can add entries to your terminfo database by running the operating system utility tic See your operating system manuals for details of how to do this. Alternatively, you can create a new set of COBOL-specific terminal details in a COBOL-specific terminfo database using the mftic utility. See Terminfo Compiler (mftic) for details.

Notes:

  • If you use an attribute that is defined in your terminfo, but your terminal does not recognize it, the attribute is not displayed and no error message is given.
  • Any attributes in ACCEPT or DISPLAY statements are automatically disabled by the run-time system if your terminal uses character positions to store attributes. This is the case for terminals that support the magic cookie glitch; that is, terminals that have "xmc" defined in their terminfo file.
Parent topic: Optional Entries
Related information
Terminfo Compiler (mftic)
Terminfo Lister (mfinfocmp)


Special Terminal Facilities

The following sections cover special terminal considerations.

  • Wyse Terminal Support
  • Control and Alt Key Support
  • Wide Terminal Mode
Parent topic: Terminfo Database and Terminal Devices


Wyse Terminal Support

Your Micro Focus COBOL system supports terminals, such as Wyse terminals, whose escape sequences are prefixed with a character other than escape (0x1b). The cursor and function keys are fully operable.

Parent topic: Special Terminal Facilities


Control and Alt Key Support

Most UNIX terminals are not capable of detecting the Alt, Ctrl and a number of other keys (such as Shift) when they are pressed alone. Therefore, an alternative is provided. Enter /a to simulate the depression or release of the Alt key. Enter /c to simulate the depression or release of the Ctrl key.

To use the forward slash character, enter it twice: //. To get help on these and other keyboard mappings, enter /m. See UNIX Key Usage Chart for a list of keystroke mappings.

Parent topic: Special Terminal Facilities
Related information
UNIX Key Usage Chart


Wide Terminal Mode

This facility is for use with COBOL only, and enables you to use a wide mode if it is supported on your terminal; for example vt100 style terminals have a 132 column mode. All normal methods of screen output are allowed including ANSI DISPLAY, Adis DISPLAY and the cobprintf() call. Cursor addressing must be consistent with the current terminal mode. For example, if you ask Adis to position the cursor at column 100 while in 80 column mode, this is not successful, neither does it cause an automatic switch from normal to wide mode. Wide mode must be set explicitly as shown below.

To use this facility you must include a record in the Working-Storage Section of your program as follows:

01 mode-number pic x comp-x.

then at run time you use the following call:

call "cobtermmode" using mode-number

where mode-number can have one of the following values:

Value | Meaning
0 | Standard terminal mode. The standard terminal terminfo file is used.
1 | Wide terminal mode. The standard terminal name suffixed by -w is the name of the terminfo file used.

The value of RETURN-CODE is set to zero if the call completes successfully. It is set to non-zero if the call fails, for example if the required terminfo file cannot be found. The method of searching for terminfo is described in Searching Portable and System Terminfo Databases.

If the call is successful, the screen handling system is initialized (if it was not already) and:

  • A RETURN-CODE of zero is returned.
  • Adis restarts in the new mode.
  • All character and attribute maps are cleared.
  • The screen is cleared and the cursor positioned in the home position.

As the screen handling system is now initialized, all DISPLAY statements now use it, including ANSI DISPLAY statements.

If the call fails, the RETURN-CODE is nonzero and the screen does not change. The RETURN-CODE is set as follows:

Value | Meaning
0 | Operation successful.
1 | The terminfo file has not been found, is not readable, is corrupt or there is not enough memory.
2 | The terminfo file does not contain one or more of the required capabilities.
3 | The environment does not support the requested code.

When using the cobtermmode call, you must be aware of the following:

  • The number of columns in wide mode must not exceed 255 .
  • When running under Animator, this call causes the terminal to be initialized to the new mode, which can produce some flicker of the display. Switching between Animator and user screens causes mode changes as the wide terminal mode is not supported for Animator's screen.
  • When the run-time system exits, the terminal is restored to normal mode. This applies only to mode changes made under the control of this call.
  • Since the usual path-searching rules are used, if the directory pointed to by COBTERMINFO contains an entry for the terminal in normal mode, but not wide mode, but the system terminfo directory does contain an entry for that terminal in wide mode, the normal mode uses the COBTERMINFO version and wide mode uses the system version. This can cause unexpected results where the two files differ in capabilities other than column size changes.
  • If you have already set the TERM environment variable to indicate that a wide mode is required (that is the TERM value already has a -w suffix), issuing the call to use wide mode results in a suffix of "-w-w". This almost certainly fails, unless the terminal has a double wide mode and a terminfo file for this mode is available.

To cause the terminal to switch states, six terminfo facilities are used:

Full Name | Abbreviated Name
init_1string | is1
init_2string | is2
init_3string | is3
reset_1string | rs1
reset_2string | rs2
reset_3string | rs3

These are fully documented in the AT&T UNIX System V Interface Definition (SVID) and are used as follows:

  • When the screen libraries start up normally, is1, is2 and is3 are output in that order. When the terminal mode is changed, rs1, rs2, rs3 are output, then is1, is2, is3 of the new terminfo are output in that order.
  • Standard terminfos can contain the column switching sequences in either the rsx family or the isx family, hence both need to be used. Terminfos that do not provide it in either need to be modified, or a new terminfo file needs to be supplied.

Ensure that the terminal mode and terminfo specified by the terminal name in TERM match when you run an application.

Parent topic: Special Terminal Facilities
Related information
Searching Portable and System Terminfo Databases


The Portable Terminfo Utilities mftic and mfinfocmp

The UNIX operating system enables applications to handle terminal I/O from any terminal attached to the system, though each terminal can be of a different type with different capabilities. It does this using a database of terminal types, the terminfo database, that includes a file for each type of terminal. Each terminfo file holds details of the capabilities of the terminal-type identified by the filename. The details are stored in a machine-readable, compiled format that is specified in the entry for term(4) in your operating system documentation. The specification includes an initial generic portion and allows for a subsequent vendor-specific portion.

Each vendor's UNIX generally provides a utility, tic, that creates a terminfo file from human-readable parameters given in a terminfo "source" file and a utility, infocmp, that creates a terminfo source file from a compiled terminfo file. Both utilities assume the vendor-specific format for the terminfo file.

This COBOL system uses the terminfo database to handle any terminal I/O that your applications require. It uses the generic portion of the terminfo file and ignores any vendor-specific portion. It uses only some of the terminal capabilities that can be specified; some are mandatory and some are optional.

Two machines running UNIX from two different vendors and having identical terminal types attached can run the same COBOL application. This COBOL system can use an identical terminfo file on each machine. However, it can be difficult to exploit this capability if a UNIX vendor does not conform to the standard for the generic portion of the terminfo file or if a UNIX vendor adds a vendor-specific portion to the terminfo file that is inconsistent with that from other vendors.

You can solve this problem by using the COBOL system utilities mftic and mfinfocmp in place of the system utilities tic and infocmp. Both COBOL utilities can operate in the following two modes:

  • Micro Focus format mode
  • UNIX vendor-specific format mode

Micro Focus mode assumes that the terminfo file format comprises only the standard generic portion of the specification and that only the capabilities recognized by this COBOL system are present. This format is fully portable between different versions of UNIX; however, it might not include all the capabilities required by non-COBOL applications.

UNIX vendor-specific mode assumes that the terminfo format is fully compatible with the system tic and infocmp utilities. This format is generally not portable between different versions of UNIX, but it does enable you to define all the capabilities available to non-COBOL applications.

For a detailed description of the terminfo source and binary formats, including the list of capabilities your environment supports, see your operating system documentation. For a list of essential terminal capabilities required by the Micro Focus COBOL system, see Screen Handling Requirements.

  • Terminfo Compiler (mftic)
  • Terminfo Lister (mfinfocmp)
  • Search Sequence
Parent topic: Terminfo Database and Terminal Devices
Related information
Screen Handling Requirements


Terminfo Compiler (mftic)

The terminfo compiler, mftic, translates a terminfo source file from the source format to the compiled format, that is placed in a terminfo database. See Search Sequence for details of how this database is located.

mftic is compatible with tic. By default, mftic produces terminfo binaries in a Micro Focus generic format. It can also produce terminfo binaries in the same format as the system format.

mftic supports the concept of use= links, as tic does. When it encounters a use=name entry in a source file, mftic tries to augment the current terminal description with the description of the terminal name. mftic first searches for name in the current source file and if not found it searches the compiled terminfo database. If name is still not found then mftic reports an error and stops. mftic recursively follows use= links if necessary.

The command line to invoke mftic is:

 mftic [-vn] [-c] [-m] [-S] filename

where the parameters are:

-vn | Specifies whether or not the compiler gives verbose messages. The value of n is one of: 0 - suppress all messages 1 - give verbose messages
-c | Prevents the creation of terminfo binaries. When this option is used, mftic only checks the input source file for errors (it does not check use= links for errors).
-m | Produces terminfo binaries in Micro Focus format rather than in the UNIX vendor-specific format. These formats are described in the section The Portable Terminfo Utilities mftic and mfinfocmp. This is the default.
-S | Treats the input binary as UNIX vendor-specific format rather than in the Micro Focus format.
filename | The name of the terminfo source file to be compiled.
Parent topic: The Portable Terminfo Utilities mftic and mfinfocmp
Related information
Search Sequence
Terminfo Lister (mfinfocmp)


Terminfo Lister (mfinfocmp)

The mfinfocmp utility performs either of the following functions:

  • Lists a terminfo source description from the specified binary file
  • Compares two or more terminfo binary files.

The binary, compiled, files must be held in a terminfo database. See Search Sequence for details of how this database is located if the -A or -B options are not set.

The command line for invoking mfinfocmp is:

mfinfocmp [-1] [-m] [-w n] [-A dir] [-B dir] [-S]
    [filename [...]]

where the parameters are:

-1 | (Numeric one, not a lower case "L") Outputs the results in single-column format.
-w n | Limits the width of the output to n characters. The default value of n is 60.
-m | Treats the input binary file as Micro Focus format, that is, a file produced by mftic with the -m option set. Results are undefined if this option is used to list a terminfo file in system format. This is the default.
  • -A dir
  • -B dir
 Changes the location of the terminfo database when comparing two or more files. The -A option changes the database location for the first file to the directory specified. The -B option changes the database location for the second and subsequent files to the directory specified. (Note that the binary files do not usually reside in the same directory as the database. For example, the file containing details for the vt100 terminal typically resides in a subdirectory v in the database.)
-S | Treats the input binary as UNIX vendor-specific format rather than Micro Focus format.
filename Either the name of the terminfo binary file to be listed or the names of the terminfo binary files to be compared. The function performed depends on the number of filenames specified on the command line as follows:

If no file is specified, mfinfocmp takes the name held in the TERM environment variable and lists that file's terminfo source description

If one file is specified, mfinfocmp lists the given file's terminfo source description

If two or more files are specified, mfinfocmp compares the first file with the second and subsequent given files.

Parent topic: The Portable Terminfo Utilities mftic and mfinfocmp
Related information
Search Sequence
Terminfo Compiler (mftic)


Search Sequence

mftic produces, and mfinfocmp lists, compiled format terminfo files for a terminfo database. Unless an option is specified to override it, by default, the directory containing the database is located using the following search sequence:

  1. If the COBTERMINFO environment variable is set, its contents are taken to be the directory name.
  2. If the TERMINFO environment variable is set, its contents are taken to be the directory name.
  3. If neither environment variable is set, the default directory used depends on whether or not the -m option is specified. If -m is specified then the directory $COBDIR/terminfo is used; if it is not specified then /usr/lib/terminfo is used. See the sections Terminfo Compiler (mftic) and Terminfo Lister (mfinfocmp) earlier in this chapter for details on the -m option.
Note: If Micro Focus format terminfo files are placed in a database located in a directory other than $COBDIR/terminfo, then at COBOL application run time you must use the COBTERMINFO environment variable (rather than the TERMINFO environment variable) to locate this directory. If you do not do this, either COBOL or non-COBOL applications can fail to run correctly.
Parent topic: The Portable Terminfo Utilities mftic and mfinfocmp
Related information
Terminfo Compiler (mftic)
Terminfo Lister (mfinfocmp)


UNIX Key Usage Chart

Because UNIX terminals vary widely, the keys documented in this manual might not be available on your keyboard. This topic lists the actual keystrokes required to obtain the keys documented.

The table also tells you how to select soft or hard operation for the Alt and Ctrl keys. With soft operation, the Alt or Ctrl key is automatically turned off after the next keystroke. This means that whenever you want a function from the Alt menu you must hold down Alt again to get the Alt menu displayed; and similarly with Ctrl. With hard operation, the Alt and Ctrl keys work in a similar way to the Caps Lock key, in that having been pressed, they remain in effect until pressed again.

The following table lists the available functions, the key documented as resulting in that function, the keystrokes required to obtain the documented functions, and whether the keystroke can be configured (Y) or not (x).

Function | Documented Key | Mapped To | Configurable
Alternate Menu (soft) | Alt | /a | Y
Alternate Menu (hard) | Alt | /x | Y
Control Menu (soft) | Ctrl | /c | Y
Control Menu (hard) | Ctrl | /z | Y
/ | / | // | Y
Escape | Escape | /@ | Y
F1 | F1 | /1 | x
F2 | F2 | /2 | x
F3 | F3 | /3 | x
F4 | F4 | /4 | x
F5 | F5 | /5 | x
F6 | F6 | /6 | x
F7 | F7 | /7 | x
F8 | F8 | /8 | x
F9 | F9 | /9 | x
F10 | F10 | /0 | x
F11 | F11 | /- | x
F12 | F12 | /= | x
Backspace | Backspace | /b | Y
Backtab | Backtab | /T | Y
Caps Lock (upper case) | Caps Lock | /u | Y
Delete | Del | /d | Y
End | End | /e | Y
Help | F1 | /? | Y
Home | Home | /h | Y
Insert | Ins | /i | Y
Interrupt | Ctrl+Break | User defined (see Note 2) | N/A
Left Shift | Shift | /l | Y
Maphelp |  | /m | Y
Num Lock | Num Lock | /# | Y
Page Up | Page-Up | /p | Y
Page Down | Page-Down | /n | Y
Refresh | Refresh | /| | Y
Right Shift | Shift | /r | Y
Scroll Lock | Scroll | /s | Y
Tab | Tab | /t | Y

Notes:

  1. Tab is the only case-sensitive keystroke. By default, lower-case Tab (/t) provides Tab, with upper-case Tab (/T) providing Backtab.
  2. The interrupt key can be defined as follows:
    stty intr ^C
  3. The keystrokes listed above are those set up by default for your system. Those functions with a check mark (Y) in the column headed Configurable can have their associated keystroke mapped onto a keystroke of your choice. You can also configure the meta character used, which is / by default.

    To change the defaults, create the file adiskey.map and enter your choice of keys. (An example file, adiskey.xxx is supplied with this system.) On startup, your COBOL system searches for adiskey.map in the current directory, then in the directory specified by the COBDIR environment variable. If it is not found the defaults are used. The following is an example adiskey.map file:

    * Micro Focus ADISKEY keyboard mapping file. Keystrokes are
* case insensitive except for TAB which uses Upper-Case-Tab
* for the Back-Tab function. An asterisk denotes a comment.
* This file shows the default keyboard mapping

         Meta-Char   is "/"
         Soft-Alt    is "a"
         Soft-Ctrl   is "c"
         Hard-Alt    is "x"
         Hard-Ctrl   is "z"
         Left-Shift  is "l"
         Right-Shift is "r"
         Caps-Lock   is "u"
         Num-Lock    is "#"
         Scroll-Lock is "s"
         Insert      is "i"
         Delete      is "d"
         Backspace   is "b"
         Home        is "h"
         End         is "e"
         Page-Up     is "p"
         Page-Down   is "n"
         Tab         is "t"
         Escape      is "@"
         Map-Help    is "m"
         Help        is "?"
         Refresh     is "|"
Parent topic: Micro Focus COBOL Server for UNIX


Licensing

  • Using the Micro Focus Licensing Administration Tool
  • Authorizing Your Product
  • Revoking Licenses
  • Licensing Error Messages
    Messages you might encounter when working with licensing.
Parent topic: Micro Focus COBOL Server for UNIX


Using the Micro Focus Licensing Administration Tool

  • Overview
  • To start the Micro Focus Licensing Administration tool
  • To view installed licenses
  • Trial Licenses
  • Usage Log
  • Using the Licensing Services
    Guidance on using the Sentinel RMS license server when developing COBOL projects.
Parent topic: Licensing


Overview

You manage your product licensing by using the Micro Focus Licensing Administration tool.

When you install your Micro Focus product, the Sentinel RMS license server is also installed to manage your license. Depending on how your site is administering licenses, you can also request licenses from a central license server.

Some licensing tasks require Internet connectivity from your computer. For example, when you authorize your product a connection is made with a Micro Focus server to verify the authorization code you have used and return a license code string. Similarly, the revoke license process uses a Micro Focus server to revoke the existing license and then provide a new authorization code. Where Internet connectivity is required, it is highlighted in the relevant task help.

Tip: You can prevent the license server being installed by creating an empty file called SKIP_SAFENET_INSTALL and saving it in the Sentinel installation folder /var/microfocuslicensing.

This stops licensing being interrupted while updates to the server are installing. When licensing needs to be updated, remove the file and install the server manually. You can also use this process on machines where you need to preserve the production environment.

To install License Manager manually:
  1. If License Manager need to be re-installed, change to $COBDIR/safenet folder and run MFLicenseServerInstall.sh as root.

    If the latest version of license manager needs to be installed, download the latest distribution from the Micro Focus SupportLine Web site and follow the instructions on the Web site.

    From a command line, run the following as Root:
    pax -rf safenet_r4_[ platform ].pax
cd safenet
./MFLicenseServerInstall.sh

Central License Server

If your site has multiple licenses and you want to use a central license server to manage them, install the Micro Focus License Manager that is supplied with your product. Individual workstations can then be configured to obtain a license from the license server machine.

License Management System Restrictions

The Sentinel RMS license management system supplied with your product does not acknowledge or manage Micro Focus product licenses you have previously installed and that use the Micro Focus License Management System.

CAUTION:
If you are using a timed license (for example, a 30 day trial license), do not change the machine’s date and time. If you do, the license will be invalidated and you will need to call Micro Focus SupportLine.

If you need to change the machine’s date and time, make sure that you have installed a full license that is not time limited.

Uninstalling a Product that uses Sentinel RMS

When you uninstall a Micro Focus product that uses Sentinel RMS, the license server is not uninstalled. You can choose to either revoke the license(s) that you have activated for that product or keep them.

Parent topic: Using the Micro Focus Licensing Administration Tool


To start the Micro Focus Licensing Administration tool

From a command prompt type:
/var/microfocuslicensing/bin/cesadmintool.sh
Parent topic: Using the Micro Focus Licensing Administration Tool
Related information
To authorize your product using a local license server
To authorize your product manually
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses
To revoke licenses manually


To view installed licenses

  1. Start the Micro Focus Licensing Administration tool.
  2. Select the Check License Status option by inputting the corresponding list number and pressing Enter.
A list of installed licenses will be displayed and will show:
  • The name of the product licensed
  • The serial number of the license
  • The type of license
  • For limited licenses, the expiry date
  • Whether the license is hosted locally or a networked computer
Parent topic: Using the Micro Focus Licensing Administration Tool
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To authorize your product manually
To configure your workstation to use a central license server
To revoke licenses
To revoke licenses manually


Trial Licenses

Depending on your product you may have trial licenses installed. If this is the case and you have not yet authorized your full license a Trial Notice dialog box might be displayed when you run your product.

While you are using a trial license within the license period, the Trial Notice dialog box might display every time you run your product. To prevent this, enter your authorization code to obtain a full license.

Parent topic: Using the Micro Focus Licensing Administration Tool


Usage Log

The licensing system creates a usage log file that details all licensing activity. In addition to monitoring usage, the file is a useful licensing diagnostic tool.

Log files are called lservrc.log. When they reach 10MB in size they are archived to lservrc.log.xxx where xxx is an incremental number for the archive file.

The files are located in /var/microfocuslicensing/logs. As these files contain important and useful information, and to maintain disk space, it is recommended that you manage these files accordingly.

Parent topic: Using the Micro Focus Licensing Administration Tool


Using the Licensing Services

Developing COBOL projects requires that licenses are installed.

By default the Sentinel RMS license server is installed automatically in your Micro Focus product. It starts automatically and runs as a daemon.

  • To start the Sentinel RMS license server
    Steps to start the license server.
  • To stop the Sentinel RMS license server
    Steps to stop the license server.
  • To start the Micro Focus licensing daemon
Parent topic: Using the Micro Focus Licensing Administration Tool


To start the Sentinel RMS license server

Note: Normally you don't need to start the license server as it starts automatically and runs as a daemon.
Important: You need to be logged in as root user to perform this task.

You can start the license server by running lserv. The script startlserv.sh is supplied for use with Micro Focus products. It configures your environment and starts lserv with the appropriate options.

  1. Change to the licensing directory. From a command prompt enter:
    cd /var/microfocuslicensing/bin
  2. Run the start script. Enter:
    ./startlserv.sh
Parent topic: Using the Licensing Services


To stop the Sentinel RMS license server

Important: You need to be logged in as root user to perform this task.

The script stoplserv.sh is supplied for use with Micro Focus products. It configures your environment and stops lserv with the appropriate options.

  1. Change to the licensing directory. From a command prompt enter:
    cd /var/microfocuslicensing/bin
  2. Run the stop script. Enter:
    ./stoplserv.sh
Parent topic: Using the Licensing Services


To start the Micro Focus licensing daemon

The licensing daemon enables the Micro Focus licensing system to communicate with the Sentinel system. It starts automatically. If you need to restart it, do the following:

  1. Log in as root.
  2. Run /var/microfocuslicensing/bin/startmfcesd.sh.
Parent topic: Using the Licensing Services


Authorizing Your Product

Depending on your system and requirements, you can either install Sentinel RMS license server on individual computers or on a single computer that will act as a central license server. A Sentinel RMS license server is installed automatically with your product, and you can choose any machine on which it is installed to act as the central server if required.

You need an appropriate type of authorization code in order to install your license or licenses. For example, if you have ordered 50 licenses then the authorization code installs either 1 license on each of 50 machines or 50 licenses on the central server. If you do not know which type of code you need, contact your system administrator.

  • To authorize your product using a local license server
  • To authorize your product manually
  • To configure your workstation to use a central license server
Parent topic: Licensing


To authorize your product using a local license server

The task steps below describe how to authorize your product if you are using the Sentinel RMS license server that is set up on your local machine. (The license server is automatically set up when you first install your product.)

Note: Internet connectivity is required to perform this task.
  1. Start the Micro Focus Licensing Administration tool.
  2. Select the Online Authorize option by inputting the corresponding list number and pressing Enter.
  3. Enter your authorization code at the Authorization Code prompt and then press Enter
Note: If authorization fails, the user interface will allow you to attempt manual authorization.
Parent topic: Authorizing Your Product
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product manually
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses
To revoke licenses manually


To authorize your product manually

Manual authorization is necessary if your machine does not have Internet connectivity or if normal (automatic) authorization has failed.

In order to authorize your product you must have the following:
  • Write access on the license file that contains the authorization codes.
  • Your authorization code (a 16-character alphanumeric string).
  • The machine ID. To get this, start the Micro Focus Licensing Administration tool and select the Get Machine Id option by inputting the corresponding list number and pressing Enter. Make a note of the "Old machine ID".

If you have previously received the licenses and put them in a text file, skip to step 6.

  1. Open the Micro Focus license activation web page http://supportline.microfocus.com/activation in a browser.
  2. Enter your authorization code and old machine ID and, optionally, your email address in the Email Address field.
  3. Click Generate.
  4. Copy the licenses strings from the web page or the email you receive into a file.
  5. Put the license file onto your target machine.
  6. Start the Micro Focus Licensing Administration tool and select the Manual License Installation option by inputting the corresponding list number and pressing Enter.
  7. Enter the name and location of the license file.
Parent topic: Authorizing Your Product
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses
To revoke licenses manually


To configure your workstation to use a central license server

You can set up a central Sentinel RMS license server if your authorization code grants multiple licenses. A license server is installed automatically when you install your Micro Focus product, and you can use any license server installation as your central license server without additional configuration.

CAUTION:
If you change the name of your license server after you have installed licenses it will stop working.

The task steps below describe how to authorize your workstation product if you want to obtain a license from a central Sentinel RMS license server. Internet connectivity is required.

You need the IP address or server name for the central license server you want to access. You should be able to get this from your License System Administrator.

Important: We recommend that other options on Advanced Configuration are modified only under guidance from Micro Focus SupportLine.

You must have write access on the license file that contains the authorization codes.

  1. Start the Micro Focus Licensing Administration
  2. Select the Advanced Configuration option by inputting the corresponding list number and pressing Enter.
  3. Select the License server option by inputting the corresponding list number and pressing Enter.
  4. Enter the IP address or server name of the central license server and press Enter.
Parent topic: Authorizing Your Product
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To authorize your product manually
To view installed licenses
To revoke licenses
To revoke licenses manually


Revoking Licenses

  • To revoke licenses
  • To revoke licenses manually
    The manual revoke process should be followed when automatic revoke has failed.
  • To move your product license to a different computer
Parent topic: Licensing


To revoke licenses

Revoke licenses if you want, for example, to move your product to a different machine or if you no longer use your product and want to reallocate the license.

Note: Internet connectivity is required to perform this task.

You must have write access on the license file that contains the authorization codes.

  1. Start the Micro Focus Licensing Administration
  2. Select the Revoke Licenses option by inputting the corresponding list number and pressing Enter.
  3. Select the license to revoke and press Enter.
  4. Type the number of licenses to revoke and press Enter.

A new authorization code for each revoked license will be generated and saved to file on your computer. The file location and the new codes will be displayed on the screen.

Ensure that you keep the new authorization codes in a safe place. You will need them when you re-authorize your product.

Note: If there is a problem accessing the Micro Focus License Authorization Server and the revoke fails, the Revoke Product Licenses dialog box will enable options to allow manual revocation. At this point your licences are revoked and cannot be used. To obtain an authorization code you must send the License Revocation Tickets (LRTs) to Micro Focus, either by pasting them into the revoke web page or by sending the indicated file to your SupportLine representative.
Parent topic: Revoking Licenses
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To authorize your product manually
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses manually


To revoke licenses manually

The manual revoke process should be followed when automatic revoke has failed.

If automatic revocation fails, a file LRT_<datetime>.txt is created in the current directory, and the Micro Focus SafeNet License Revocation web page address displayed. Either:

  1. Click the HTTP link to go to the Micro Focus license revocation web page.
  2. Paste the contents of the file into the text box and click Generate.

    The new Authorization code will be displayed.

Or

  1. Copy the contents of the file into an email and send it to your SupportLine representative.
Important: Ensure that you keep the new authorization codes in a safe place. You will need them when you re-authorize your product.
Parent topic: Revoking Licenses
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To authorize your product manually
To configure your workstation to use a central license server
To view installed licenses
To revoke licenses


To move your product license to a different computer

If you have been using a product that has had a license provided by the local license server, you can use the product on a different computer by performing these steps

  1. Start the Micro Focus Licensing Administration tool.
  2. Revoke the license, making note of the new authorization code that will be required when you re-authorize your product.
  3. Uninstall the product.
  4. Install the product on the new computer.
  5. Start the Micro Focus Licensing Administration tool.
  6. Authorize your product with the new authorization code.
Note: You can proceed with the product uninstall without taking steps to revoke the license first. In this case, you will be guided through the revoke process as part of the uninstall.
Parent topic: Revoking Licenses
Related tasks
To revoke licenses during product uninstall
Related information
To start the Micro Focus Licensing Administration tool
To authorize your product using a local license server
To configure your workstation to use a central license server


Licensing Error Messages

  • Initialization error - Initializing: Cannot communicate with licensing daemon
    Check the licensing daemon is running.
  • Error - Initalizing: Cannot find initialization file
    The initialization file <path to Micro Focus licensing bin directory> ces.ini is missing. Verify your installation with Micro Focus SupportLine.
  • Error - Unable to manage licenses in license manager that is not running on localhost
    You have a remote license server configured. You should install the licenses on that machine or configure your license server to be the local host.
  • Error [5]: Cannot talk to the license server on host "xxx.x.x.x". Server not running
    The /etc/hosts file might not contain an entry for hostname and IP address.
  • Error authorizing... Remote request error - The authorization code is invalid
    Check the authorization code you have entered against the code provided by Micro Focus.
  • Error [26] - Request Denied due to clock tamper detection
    The clock has been changed on a machine where a time-limited license is installed.
  • Error[18]: No license code is available for feature (component)
    The license string installed on the machine does not contain the necessary license string of the component being used.
  • Unable to authorize (cause)
    The authorization code cannot be verified. The specific cause is given in the brackets. Depending on the nature of the message, further detail and instruction will accompany the message.
Parent topic: Licensing


Initialization error - Initializing: Cannot communicate with licensing daemon

Check the licensing daemon is running.

Run /var/microfocuslicensing/bin/mfcesdchk to check if the daemon is running.

If it isn't, log in as root and run /var/microfocuslicensing/bin/startmfcesd.sh to start it.

Parent topic: Licensing Error Messages


Error - Initalizing: Cannot find initialization file

The initialization file <path to Micro Focus licensing bin directory> ces.ini is missing. Verify your installation with Micro Focus SupportLine.
Parent topic: Licensing Error Messages


Error - Unable to manage licenses in license manager that is not running on localhost

You have a remote license server configured. You should install the licenses on that machine or configure your license server to be the local host.
Parent topic: Licensing Error Messages


Error [5]: Cannot talk to the license server on host "xxx.x.x.x". Server not running

The /etc/hosts file might not contain an entry for hostname and IP address.
Ensure that these values are added to the /etc/hosts file. You can find the hostname by typing hosntame from a command prompt. To obtain the IP address, type /sbin/ipconfig from a command prompt.
Parent topic: Licensing Error Messages


Error authorizing... Remote request error - The authorization code is invalid

Check the authorization code you have entered against the code provided by Micro Focus.
Parent topic: Licensing Error Messages


Error [26] - Request Denied due to clock tamper detection

The clock has been changed on a machine where a time-limited license is installed.
Contact your Micro Focus SupportLine representative in order to resolve the matter. You will be asked to provide the locking code of the machine and in return will receive a clean certificate which you run on the machine in order to restore the license to its previous working state.
Parent topic: Licensing Error Messages


Error[18]: No license code is available for feature (component)

The license string installed on the machine does not contain the necessary license string of the component being used.
Contact your Micro Focus SupportLine representative in order to obtain the correct license string.
Parent topic: Licensing Error Messages


Unable to authorize (cause)

The authorization code cannot be verified. The specific cause is given in the brackets. Depending on the nature of the message, further detail and instruction will accompany the message.
Parent topic: Licensing Error Messages


Copyright and Legal Information

  • Copyright and Trademarks
Parent topic: Micro Focus COBOL Server for UNIX


Copyright and Trademarks

Copyright © Micro Focus 1984-2012. All rights reserved. The software and information contained herein are proprietary to, and comprise valuable trade secrets of, Micro Focus, which intends to preserve as trade secrets such software and information. This software is an unpublished copyright of Micro Focus and may not be used, copied, transmitted, or stored in any manner. This software and information or any other copies thereof may not be provided or otherwise made available to any other person.

Micro Focus has made every effort to ensure that this book is correct and accurate, but reserves the right to make changes without notice at its sole discretion at any time. The software described in this document is supplied under a license and may be used or copied only in accordance with the terms of such license, and in particular any warranty of fitness of Micro Focus software products for any particular purpose is expressly excluded and in no event will Micro Focus be liable for any consequential loss.

MICRO FOCUS, the Micro Focus logo, and Micro Focus product names are trademarks or registered trademarks of Micro Focus IP Development Limited or its subsidiaries or affiliated companies in the United States, United Kingdom, and other countries. All other marks are the property of their respective owners.

IBM®, z/OS®, CICS® and RACF® are registered trademarks, and IMS™ is a trademark, of International Business Machines Corporation.

License management is based on SentinelRMS © 1989-2006 SafeNet, Inc. All rights reserved. Sentinel is a registered trademark of SafeNet, Inc.

Portions of some programming examples were produced by Dr. Frank McCown, Harding University Computer Science Dept and are licensed under a Creative Commons License.

All other trademarks are the property of their respective owners.

Reference to third party companies, products and web sites is for information purposes only and constitutes neither an endorsement nor a recommendation. Micro Focus provides this information only as a convenience to users. Micro Focus makes no representation whatsoever regarding the content of any other web site or the use of any such third party products. Micro Focus shall not be liable in respect of your use or access to such third party products/web sites.

No part of this publication, with the exception of the software product user documentation contained on a CD-ROM, may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or machine-readable form without prior written consent of Micro Focus.

Licensees may duplicate the software product user documentation contained on a CD-ROM, but only to the extent necessary to support the users authorized access to the software under the license agreement. Any reproduction of the documentation, regardless of whether the documentation is reproduced in whole or in part, must be accompanied by this copyright statement in its entirety, without modification.

U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were developed at private expense, that no part is in the public domain, and that the Software and Documentation are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 et. seq. or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at FAR 52.227-19, as applicable. Contractor is Micro Focus, One Irvington Center, 700 King Farm Boulevard, Suite 400, Rockville, Maryland 20850. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.

Parent topic: Copyright and Legal Information


Notations and Conventions

COBOL Conventions
  • PIC X is used rather than PIC 99 with the COMP-X and COMP-5 data types. Unlike PIC 99, PIC X shows the length of the data item and so demonstrates more clearly the use of COMP-X, which is to define a binary item of the specified number of bytes.
Command Line Format
  • Words printed in italics are generic terms representing names to be devised by you.
  • Words printed in nonitalic characters are the actual words you must enter. You must type them in upper or lower case as shown.
  • Material enclosed in square brackets [ ] is optional.
  • When material is enclosed in braces { }, you must choose from the options within them. If there is only one option in the braces, the braces indicate repetition.
  • The ellipsis (. . .) follows { } or [ ] and means you can repeat the material in the { } or [ ]. The number of repetitions allowed is unlimited unless otherwise stated. If the ellipsis is used with [ ] the material can be omitted altogether.
  • If a command line does not fit across the page, it is continued on the next line; the continuation line is indented.
  • The Help may refer you to the readme for details specific to a particular UNIX platform.
  • All command line formats and examples are for the standard UNIX shell, the Bourne shell. If you are using another shell, see your UNIX documentation for the appropriate formats.
  • Where examples showing environment variables do not specifically show them being exported to the shell, it is treated as implicit that they are exported.
  • Some keystrokes using function keys or the Alt or Ctrl keys are not available on all UNIX platforms.The UNIX Key Usage Chart shows how the keystrokes shown in the Help map onto actual keystrokes.
Help System
  • F1=Help appears on every menu in character-mode Micro Focus software. It invokes a help screen describing the current menu.
Keyboard Keys
  • Key names and menu choices are emboldened within the text.
  • Enter refers to the carriage return or Enter key. Where commands to be typed are shown, the Enter key is not explicitly shown; it is treated as implicit that Enter must be pressed at the end of the line.
Numbers
  • Hexadecimal numbers are enclosed in quotation marks and preceded by a lower-case "x" or "h"; for example, x"9D", h"03FF". The "x" is used when the hexadecimal number represents a character string; the "h" when it represents a numerical value.
Path Specifications
  • All path specifications are based on installation to the default installation directory. If you have installed Visual COBOL to a non-default installation directory, adjust the path specifications accordingly.
User Interface
  • Menu choices, and UI control and field names are emboldened within the text.
  • In some environments, you might notice that what appears on your screen differs in minor ways (for example, version numbers) from that illustrated in this Help. This does not affect the operation of your software.
Parent topic: Micro Focus COBOL Server for UNIX


Deployment Licensing

Related concepts
Overview of Deploying Native COBOL Applications


Database Access under Enterprise Server

The execution of container-managed services running against any XA-compliant database is supported.

A switch module that gives access to the database's XA switch structure is supplied for the following databases:

Enterprise Server supports the execution of applications running against any XA-compliant database. Micro Focus provides a switch module which provides Enterprise Server with access to the database's XA switch structure for the following databases:

The availability of the switch modules differs between platforms, as follows:

Feature/Platform | DB2 32-bit | Oracle 32-bit | DB2 64-bit | Oracle 64-bit
IBM System p running AIX | X | X | X | X
Itanium running HP-UX | X | X | X | X
x86-64 running Red Hat Linux | X | X | X | X
Itanium running Red Hat Linux |  |  |  |
IBM System z running Red Hat Linux | X |  | X |
SPARC running Solaris | X | X |  | X
x86-64 running SuSE Linux | X | X | X | X
IBM System z running SuSE Linux | X |  | X | X
Related information
Resource Managers


Overview of Deploying Native COBOL Applications

Note: The following applies to native COBOL only.

Native applications developed using a COBOL development system require a COBOL run-time server to provide the necessary run-time system and support.

COBOL Server is your COBOL run-time server. It is supplied as part of Visual COBOL, which is your COBOL development system. COBOL Server is also supplied separately.

End users need to install COBOL run-time licenses before they can run applications that use the COBOL run-time system.

You need to:

  • Ship COBOL Server with your application.
  • Ensure that the application you have developed has the proper COBOL Server licenses. Your end users need to install the licenses before they can run the application. This is done by using the Micro Focus Licensing Administration Tool. The license Authorization Code, required to license the application, is either supplied when you ship the COBOL run-time server with the application or by end-user request from Micro Focus.
Note: This product is available in two variants which you can install and use with the same license - COBOL Server which is the deployment environment for COBOL applications created with Visual COBOL for Visual Studio 2010 or Visual COBOL for Eclipse, and COBOL Server 2012 which targets applications created with Visual COBOL for Visual Studio 2012.

Visual COBOL for Visual Studio 2010 and Visual COBOL for Visual Studio 2012 each target a different version of the COBOL run-time system - COBOL Server and COBOL Server 2012, respectively.

Ensure that after you've edited the project in the preferred version of Visual Studio, you compile your source code in that version of Visual COBOL which targets the version of the COBOL run-time in which you want your applications to run.

For example, if you build your application using Visual COBOL for Visual Studio 2010 you cannot deploy the target files to COBOL Server 2012; you must use COBOL Server.

Related information
Deployment Licensing


COBOL Server Installation Options

To install COBOL Server you run setup_visualcobol_server_2.1_platform which contains a number of product .msi files (Windows Installer packages). When run, setup_visualcobol_server_2.1_platform performs some initial system checks then sequentially installs the MSIs.

setup_visualcobol_server_2.1_platform can take a number of parameters, enabling you to specify a number of different types of installation:

  • Standard Installation
    • Format:
    • setup_visualcobol_server_2.1_platform
    • Summary:
    • Full installation including License Manager, Vision, and COBOL Server. During installation you can specify options including the location to which the components are installed.
  • Non-interactive Installation
    • Format:
    • setup_visualcobol_server_2.1_platform /qb
    • Summary:
    • Full installation, but the components are installed non-interactively using default options and directories.
  • Silent Installation
    • Format:
    • setup_visualcobol_server_2.1_platform /q
    • Summary:
    • Full installation, but the components are installed non-interactively with no user interface, using default options and directories.
  • Modified Silent Installation
    • Format:
    • setup_visualcobol_server_2.1_platform /q /componentargs "Micro Focus COBOL Server":"INSTALLDIR=d:\cobolrts"
    • Summary:
    • Full installation, but the installation is controlled by the /componentargs switch and the standard MSI property INSTALLDIR. In the example above, COBOL Server is installed into d:\cobolrts.
Note:
  • You can display the valid values for the /componentargs switch by using the /displayconfig switch:

    setup_visualcobol_server_2.1_platform /displayconfig

  • Log files that are created during installation are saved in the folder specified by the TEMP environment variable.
  • You can extract the component .msi files from setup_visualcobol_server_2.1_platform by using the by using the /extractcab switch:

    start /wait setup_visualcobol_server_2.1_platform /extractcab

    The extracted .msi files are saved in the SupportFiles subfolder.

Related information
Shipping Selected Files from COBOL Server


Configuring Environment Variables

You can use Enterprise Server environment variables to configure many server instance environment properties. This section contains information on setting environment variables, and on the environment variables that are available.

Tip: This section contains an alphabetical listing of environment variables, and environment variables listed by functional group. For variable values, check the alphabetical listing, and if this does not contain values, search the online help for the variable name.


To revoke licenses during product uninstall

When you uninstall a product, the Micro Focus License Manager software performs a check to see if any licenses for that product exist on your computer. If so, you will be prompted to revoke them. If you do revoke them, they will be removed and you will be given you a new authorization code. You use this new code to generate a license when you install the product on another machine.

If you are going to re-install your product on the same machine, you do not need to revoke the license. In this case, select Keep when you are prompted to revoke the license.

  1. Uninstall your product.

    A prompt will display to reallocate your licenses.

  2. Select Revoke if you want to revoke the licenses.

    The Micro Focus License System Administration tool is displayed at the Revoke tab.

  3. Select the product license you want to revoke.
  4. Click Revoke.

    After a check has been made to ensure no licensed products are running, the Revoke Product Licenses dialog box is displayed.

  5. Input or select the number of licenses you want to revoke.
  6. Click Revoke.

    A new authorization code for each revoked license will be generated and saved to file on your computer. The file location and the new codes will be displayed on the screen.

    Ensure that you keep the new authorization codes in a safe place. You will need them when you re-authorize your product(s) .

Note: If there is a problem accessing the Micro Focus License Authorization Server and the revoke fails, the Revoke Product Licenses dialog box will enable options to allow manual revocation. At this point your licences are revoked and cannot be used. To obtain an authorization code you must send the License Revocation Tickets (LRTs) to Micro Focus, either by pasting them into the revoke web page or by sending the indicated file to your SupportLine representative.


Shipping Selected Files from COBOL Server

Note: The following applies to native COBOL only.
CAUTION:

We recommend that you ship the whole of COBOL Server with your application. However to provide backward compatibility, you can still select and ship specific files.

The COBOL Server files you need to ship with your application depend on how you linked the application, the type of executable it is, and the support functionality it uses.

You can package the files you need in whatever you choose, such as by creating .dll files from the supplied .obj files or by combining the necessary .gnt files into an .lbr file.

When you ship a modular application , you need to ship the following files:

  • The main program of your application
  • Any dynamically linked programs that are part of your application, including objects that have been linked into dynamic link libraries
  • The Microsoft Visual C++ run-time system
  • Licensing files
  • The National Locale Support message files for the locales that you support:
    • lang\default\*
    • lang\en_GB\*
    • lang\en_us\*
    • lang\jp_sj\*

In addition, you need to ship the following files depending on your application requirements:

  • The file adisctrl, if your application uses the enhanced ACCEPT/DISPLAY syntax, and you have configured it to use a non-default configuration
Related information
COBOL Server Installation Options


To enable your annotation files in the CTF Viewer

  1. Click Window > Preferences > Micro Focus COBOL > Consolidated Trace Facility > Annotation File Locations.

    Initially, the Location field is populated with the location of the trace files. This location is defined in the MFTRACE_ANNOTATIONS environment variable, which is set automatically in the Visual COBOL command environment from which you start Eclipse.

  2. Set the location to point to where your trace files are. You can add multiple locations and retain or remove the default location.
  3. Set the order of the trace file locations, so that the first location is used if trace files are found there.

The locations are preserved between Eclipse IDE sessions.

Related concepts
CTF Trace File Formats
Example CTF Configuration Files