Micro Focus COBOL Server 2.2 for UNIX

Welcome to COBOL Server

  • Welcome
  • Product Information
  • Managing Licenses

What's New

  • New Features in COBOL Server 2.2

Featured Sections

  • Enterprise Server
  • Running an Application from the Command Line
  • 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.

  • The Micro Focus Community
  • New Features
  • Product Information
  • Managing Licenses
Parent topic: Micro Focus COBOL Server 2.2 for UNIX


The Micro Focus Community

In addition to this product documentation, visit the Micro Focus Community Web site to browse the Knowledge Base, read articles and blogs, as well as discuss this product with other users and Micro Focus specialists.

Parent topic: Welcome


New Features

  • New Features in COBOL Server 2.2
  • Features Added in COBOL Server 2.1 Update 1
  • Features Added in COBOL Server 2.1
Parent topic: Welcome


New Features in COBOL Server 2.2

  • Consolidated Tracing Facility
  • Interface Mapping Toolkit
  • Support for SOA
Parent topic: New Features


Consolidated Tracing Facility

The following changes have been made to the Consolidated Tracing Facility (CTF):

CTF for JVM COBOL applications

CTF tracing is now supported in JVM COBOL applications.

New emitters

A new emitter, JAVALOGGER, is available for JVM COBOL web applications. This emitter passes details to the Java logging API that is available through your web server. Use this emitter if you are unable to configure the TEXTFILE or BINFILE emitters due to web server permission restrictions.

New properties and variables for existing emitters

The following support has been added to existing emitters.

The following property has been added to the BINFILE emitter:

Property | Description
RunUnitID | Controls whether the RunUnit information is included in the trace.

Four new pseudo-variables for the FILE property have been added to the BINFILE and TEXTFILE emitters:

pseudo-variable | Description
$(PLATFORM) | A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files
$(RUNUNIT) | A unique number that represents the managed RunUnit ID
$(RUNUNIT_SESSIONNAME) | The session name passed to the managed RunUnit
$(RUNUNIT_GUID) | The globally unique identifier associated with the managed RunUnit
Parent topic: New Features in COBOL Server 2.2


Interface Mapping Toolkit

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Visual COBOL now supports the creation and deployment of COBOL program-based services using the Interface Mapping Toolkit (IMTK).

Parent topic: New Features in COBOL Server 2.2


Support for SOA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Visual COBOL now includes support for creating Web service and Enterprise Java Bean applications using the Interface Mapping Toolkit (IMTK) in conjunction with Enterprise Server. If you are upgrading to this release from an earlier version of Visual COBOL, you may need to apply for a new authorization code in order to access the functionality - please contact Micro Focus SupportLine to receive an updated authorization code. Note that the Visual COBOL Personal Edition license does not support the IMTK functionality.

Parent topic: New Features in COBOL Server 2.2


Features Added in COBOL Server 2.1 Update 1

Parent topic: New Features


Features Added in COBOL Server 2.1

  • ACUCOBOL-GT Data Types in Managed Code
  • ACUCOBOL-GT Library Routines in Managed Code
  • Compiler Directives
  • .int, .gnt and .lbr File Types Support
  • JVM Class Library
  • Managed COBOL Enhancements
  • OpenESQL
Parent topic: New Features


ACUCOBOL-GT Data Types in Managed Code

ACUCOBOL-GT data types and sign() variants that were previously only available in native code are now supported in managed code. Use the Compiler directives COMP1 and COMP2 to set ACUCOBOL-GT behavior for those particular data types.

Parent topic: Features Added in COBOL Server 2.1


ACUCOBOL-GT Library Routines in Managed Code

ACUCOBOL-GT library routines that were previously only available in native code are now supported in managed code.

Parent topic: Features Added in COBOL Server 2.1


Compiler Directives

The following new Compiler directives are now available:

DISPLAY
Defines the default behavior of standard DISPLAY statements.
COMP1
Specifies the behavior of a COMP-1 data item.
COMP2
Specifies the behavior of a COMP-2 data item.
RESTRICT-GOTO
Generates a syntax error for GO TO statements that transfer control to outside of the current section.
ILSMARTRESTRICT
Limits the generation of properties in ILSMARTLINKAGE classes to non-redefining elementary items.

The following Compiler directive has changed:

  • DATAMAP - Two new parameters allow you to display either the address or offset values for data items in your program.
Parent topic: Features Added in COBOL Server 2.1


.int, .gnt and .lbr File Types Support

Support has been added within the IDE for compiling native COBOL applications to the Micro Focus legacy formats .int and .gnt, and to package these files as a Micro Focus library file (.lbr). Improvements include:

  • An option to compile all native COBOL projects to .int and .gnt code. You can set this in your project's properties.
  • An option to package the .int and .gnt files produced by the project as a Micro Focus .lbr library files.
  • Improvements to the Net Express Project Import wizard that enable you to convert existing Net Express projects to Visual COBOL projects that compile to .int and .gnt code.
Parent topic: Features Added in COBOL Server 2.1


JVM Class Library

A new class library, com.microfocus.cobol.runtimeservices, has been introduced to help you integrate JVM COBOL and Java in the same application.

The library contains the following classes:
CallableProgram
Provides a class and annotation that you can use to create a class that can be called from COBOL.
Interop
Provides a class that contains helper methods for loading, calling and cancelling a program.
RunUnit
Provides a container class that allows you to use COBOL programs in a multi user/session environment.

Full information on these classes is available in Javadoc format for integration in the Eclipse IDE.

Parent topic: Features Added in COBOL Server 2.1


Managed COBOL Enhancements

Delegates and Events
Delegates and events are now implemented on the JVM platform.

This release provides support for combining delegates, using the METHOD keyword to specify method groups, and implicit conversion from a method group or an anonymous method to the suitable delegate type.

Handling Invalid Numeric Data
The handling of invalid numeric data is controlled by a number of Compiler directives: HOSTNUMMOVE, HOSTNUMCOMPARE and SIGNFIXUP. These directives were previously only available in native code but are now supported in managed code.
Resolving Types
In this release, the Compiler attempts to resolve types to those defined in the current compilation unit wherever possible. The Compiler will attempt to resolve such types to an external name only if no suitable type exists in the current compilation unit. For example:
$set ilusing"System"
class-id MyNamespace.EventHandler.
01 o type EventHandler.
end class.

In this release, 01 o type EventHandler. resolves to MyNamespace.EventHandler and not to System.EventHandler.

Specifying Properties
In previous versions of the products, properties declared using the PROPERTY keyword on a data item were generated as final properties. Starting with this release, they are generated as virtual properties by default. In order to make the properties final, you need to specify the word FINAL following PROPERTY. This change may affect the generation of Proxy classes, for example, if you are using WCF.
Parent topic: Features Added in COBOL Server 2.1


OpenESQL

SQL Server
We now support Microsoft SQL Server 2012.
Parent topic: Features Added in COBOL Server 2.1


Product Information

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

  • Installing the Product
  • Updates and Product Support
  • Micro Focus End User License Agreement
  • 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
  • Additional Software Requirements
Parent topic: Installing on UNIX


Hardware Requirements

The disk space requirements are approximately:

Platform | COBOL Server (MB) | Sentinel RMS license server (MB)
POWER running AIX | 281 | 26
HP IA | 638 | 54
System Z running Red Hat Linux | 234 | 28
x86-64 running Red Hat Linux | 251 | 33
SPARC running Solaris | 296 | 31
x86-64 running Solaris | 266 | 23
System Z running SuSE SLES | 237 | 28
x86-64 running SuSE SLES | 252 | 33
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
Related information
Operating Systems Supported
Software Requirements
Additional Software Requirements


Operating Systems Supported

  • POWER running AIX 6.1 TL7 SP5/7.1 TL1 SP5 - 32/64-bit
  • x86-64 running Red Hat Linux 5.5/5.8/5.9/6.3/6.4, Oracle Linux 6.3 with Red Hat Kernel compatibility mode, Oracle Linux 6.3 with Unbreakable Enterprise Kernel - 32/64-bit
  • SPARC running Solaris 10/11/11.1 - 32/64-bit
  • x86-64 running Solaris 10/11/11.1 - 32/64-bit
  • x86-64 running SuSE SLES 11/11 SP2/11 SP3 - 32/64-bit
  • System Z running SuSE SLES 11 SP2/11 SP3 - 32/64-bit
  • System Z running Red Hat Linux 6.2/6.3- 32/64-bit
  • HP IA 11.31 - 32/64-bit
Parent topic: System Requirements for COBOL Server for UNIX
Related information
Hardware Requirements
Software Requirements
Additional Software Requirements


Software Requirements

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

  • The Korn shell is required for the licensing daemon. After the installation, if the licensing daemon does not start, check and ensure the Korn shell is installed and then run the /var/microfocuslicensing/bin/startmfcesd.sh script to start the daemon.
  • The pax archiving utility is required by the setup file. Pax is distributed with most UNIX/Linux systems but, if it is missing, you must install it separately. To verify pax is installed, run pax --help or pax --version at the command line.
  • On Red Hat 6.x, you must have the following operating system libraries installed:
    • glibc-*.x86_64
    • glibc-*.i686
    • libgcc-*.x86_64
    • libgcc-*.i686

    Visit the Red Hat Web site for more information.

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.

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

  • You need to 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
  • JavaScript or scripting support must be enabled in your browser, so that Enterprise Server Administration is usable. Also, active content must be allowed and not blocked.
Parent topic: System Requirements for COBOL Server for UNIX
Related information
Hardware Requirements
Operating Systems Supported
Additional Software Requirements


Additional Software Requirements

To ensure full functionality for some COBOL Server features, you might be required to obtain and install additional third-party software in addition to the prerequisite software installed automatically by the COBOL Server setup file. The following information specifies the third-party software required for each feature.

Consolidated Trace Facility

  • The Microsoft .NET Framework 2.0 or later is required for the CTF Viewer. It is available from the Microsoft .NET downloads area.

Java Compilation

  • Either the IBM or the Oracle Java Development Kit (JDK), version 1.5 or later, is required for compiling Java. The JDK is downloadable from the Oracle and IBM Web sites. 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

XML Extensions

  • XML Extensions has the same requirements as Visual COBOL. Both 32-bit and 64-bit versions are available. See the Visual COBOL XML Extensions User's Guide, available from the Visual COBOL product documentation section of the SupportLine website, for more details.
  • Additionally, XML Extensions may be used in conjunction with Terminal Server.
  • Database Access
  • Java Development Kit (JDK)
Parent topic: System Requirements for COBOL Server for UNIX
Related information
Hardware Requirements
Operating Systems Supported
Software Requirements


Database Access

Before you can use COBOL Server to deploy SQL applications developed with OpenESQL, DB2 ECM, or COBSQL, ensure any third-party software prerequisites are installed and the environment is set properly. Refer to the your product help, Welcome > Product Information > Installing... > System Requirements... > Additional Software Requirements > Database Access, for details.

Parent topic: Additional Software Requirements


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: Additional Software Requirements


Installing COBOL Server for UNIX

  1. Downloading the Product
  2. Installing
  3. After Installing
  4. Installing as an Upgrade
  5. 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.
  6. UNIX Installer Issues
  7. Repairing
  8. 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 installation instructions and the End User License Agreement.

Parent topic: Installing COBOL Server for UNIX
Next topic: Installing


Installing

These are the steps to install this product:

  1. Give execute permissions to the setup file:
    chmod +x setup_cobol_server_2.2_platform
  2. Run the installer with superuser permissions:
    ./setup_cobol_server_2.2_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/product-name, (COBDIR).

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

    ./setup_cobol_server_2.2_platform -installlocation="full path of new location"
    Note: You can use variables or the tilde syntax for the path for –installlocation. For example, the following examples are equivalent:
    -installlocation="/home/myid/installdir"
    -installlocation="~myid/installdir"
    -installlocation="~/installdir"
    -installlocation="$HOME/installdir"

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

    You can use the following options to configure the Enterprise Server installation: [ -ESsysLog="location" ] [ -ESadminID="User ID" ] [ -CASrtDir="location" ], where:
    -ESsysLog
    Specifies a location in which the build will create the Enterprise Server System log file - for example, -ESsysLog="/home/esuser/logs". The default location is /var/mfcobol/logs.
    -ESadminID
    Sets the Enterprise Server System Administrator Process User ID from the command line - for example, -EDadminID="esadm". The default user ID is the one that runs the installer.
    -CASrtDir
    Specifies the location were the Enterprise Server run-time system files are placed - for example, -CASrtDir="/home/esuser/casrt/es". The default location is /var/mfcobol/es.
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_cobol_server_2.2_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 licensing needs to be updated later, remove the file and install Sentinel RMS server manually.

Parent topic: Installing COBOL Server for UNIX
Previous topic: Downloading the Product
Next topic: After Installing


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 -V
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 (such as etc/profile, etc/bashrc).

Note that cobsetenv is only compatible with POSIX-like shells, such as bash, ksh, or XPG4 sh. It is not compatible with C-shell or pre-XPG4 Bourne shell.

Parent topic: Installing COBOL Server for UNIX
Previous topic: Installing
Next topic: Installing as an Upgrade


Installing as an Upgrade

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

  • Move the existing installation to a different location and install the latest version to the default install location specified by the COBDIR environment variable ( /opt/microfocus/VisualCOBOL, by default).

    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/VisualCOBOLversion
    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 COBOL Server installer with the –installlocation option:
    1. Execute the following command:
      . /InstallFile -installlocation="/opt/microfocus/VisualCOBOL"
      Note: You can use variables or the tilde syntax for the path for –installlocation. For example, the following examples are equivalent:
      -installlocation="/home/myid/installdir"
      -installlocation="~myid/installdir"
      -installlocation="~/installdir"
      -installlocation="$HOME/installdir"
    2. Execute cobsetenv to set the environment and point to the new install location:
      . /opt/microfocus/VisualCOBOL/bin/cobsetenv

      Note that cobsetenv is only compatible with POSIX-like shells, such as bash, ksh, or XPG4 sh. It is not compatible with C-shell or pre-XPG4 Bourne shell.

Parent topic: Installing COBOL Server for UNIX
Previous topic: After Installing
Next topic: Installing Silently


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/Linux:

–silent -IacceptEULA

For example, execute:

setup_filename –silent -IacceptEULA
Parent topic: Installing COBOL Server for UNIX
Previous topic: Installing as an Upgrade
Next topic: UNIX Installer Issues


UNIX Installer Issues

Licensing Daemon
If the Korn shell is not installed on your machine when you run the installer, the licensing daemon will not be started. To resolve this after you install the product, install the Korn shell and then run the /var/microfocuslicensing/bin/startmfcesd.sh script to start the daemon.
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
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
Previous topic: Installing Silently
Next topic: Repairing


Repairing

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

Parent topic: Installing COBOL Server for UNIX
Previous topic: UNIX Installer Issues
Next topic: Uninstalling


Uninstalling

Note: Before you uninstall the product, ensure that the Enterprise Server instances and the Micro Focus Directory Service (MFDS) are stopped.

To uninstall this product:

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

To uninstall Micro Focus License Administration:

  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
Previous topic: Repairing


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


Known Errors and Restrictions

The following known errors and restrictions apply to COBOL Server:

  • Application-Managed Services
  • Enterprise Server
  • Error Messages
  • ESM
  • FaultFinder
  • File Handler
  • GDG Limit Change
  • JCL Utilities
  • Run-Time System
  • Security Management
  • Spool File Format Change
Parent topic: Product Information


Application-Managed Services

If you have configured Enterprise Server to support container-managed services by defining external XA resource managers, any application-managed service that issues CONNECTs to, or DISCONNECTs from, one of these defined resource managers might receive warning- level response codes.

Parent topic: Known Errors and Restrictions


Enterprise Server

Upgrading Enterprise Server

If you upgraded from a version of Micro Focus Server and have retained any enterprise servers that have a Web Services listener, you will receive an error when you deploy informing you that the listener cannot be found. To fix this, change the listener name before deploying using one of the following methods:

  • From Enterprise Server Administration, change the listener name from Web Services to Web Services and J2EE.
  • Edit your deployment service (usually named Deployer) and add the following lines to the Configuration Information area: [destination] listener=Web Services
  • If your deployment service doesn't have the listener name specified, edit the base\deploy\.mfdeploy file changing the Web Services listener name to Web Services and J2EE .
Dynamic Debugging with Enterprise Server

If dynamic debugging is not enabled for the enterprise server on which you are running an application, you receive an alert when you try to debug. You need to enable dynamic debugging for the server by checking Allow Dynamic Debugging on the Edit page of Enterprise Server Administration and restarting the server or by checking Dynamic Debug on the ESMAC > Control page which will enable debugging until the server is stopped.

Enterprise Server Administration Web page

If the buttons on the Enterprise Server Administration Web page don't work, you need to enable Active Scripting or Javascript in your browser.

-541326

Active Content Blocked

If the Web Browser tells you it's blocking active content, when you view the Help, you need to allow active content.

Viewing the Help

You can view the COBOL Server Help in a separate browser window while you are using the Enterprise Server Administration Web interface, by clicking Contents in the menu at the left-hand side of the page. For this link to work, you must have the following in place:

  • An enterprise server that has a Web listener with the following entry in the [virtual paths] section: docs=<ES>/help
  • The enterprise server must be started
ESDEMO Configuration

The default enterprise server, ESDEMO, may not have the correct configuration information entry for its Web listener. If you encounter problems accessing the Help while you are using ESDEMO, you must correct the entry using the Edit Listener page. Note that references to this configuration entry in the context help and the Enterprise Server Configuration and Administration Guide are no longer correct and you must use the entry as specified above.

When you create a new enterprise server, a Web listener with the required configuration information entry is automatically created.

Parent topic: Known Errors and Restrictions


Error Messages

If run-time system error 249 occurs, the message displayed is "249 error message text not found (Signal <signal-number>)". The message should be "249 Process killed (Signal <signal-number>)". See the documentation for more information on this error.

CASMQ1011E

Undocumented error message.

CASMQ1011E: Unexpected error while connecting to queue manager
in IMS Trigger Monitor, status: cc: 00002, rc: 02058

The error message indicates that the Trigger Manager could not establish a connection with the MQSeries Queue Manager for some reason.

The MQSeries completion code and reason code are displayed as part of the error message. In this particular case, reason code 2058 indicates a Queue Manager Name error. The queue manager name that is specified as a JCL parameter in the job that starts the Trigger Monitor is not valid

CASSI9012E

Undocumented error message.

CASSI9012E JCL support failed to start. Error returned from casspool, RC=n

The error message indicates that JCL support failed to start, because the call to casspool failed with the displayed return code (n). We advise you to perform a repair install on your system.

Parent topic: Known Errors and Restrictions


ESM

  • Legacy security is not currently supported on UNIX for 64-bit regions.
Parent topic: Known Errors and Restrictions


FaultFinder

The FaultFinder tool has been removed from the current version of COBOL Server. This includes the removal of the following tunables:

  • faultfind_level
  • faultfind_outfile
  • faultfind_recsize
  • faultfind_config
  • faultfind_cache_enable

You should either remove these tunables from your application or set the tunable cobconfig_error_report=false in your configuration file.

You should also remove any calls to the library routine CBL_FFND_REPORT, as this now produces a COBRT107 Operation not implemented in this run-time system (fatal) error.

Parent topic: Known Errors and Restrictions


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


GDG Limit Change

The GDG-LIMIT value for Generation Datasets has changed

After you install the product, the GDG-LIMIT value conversion is handled automatically. The GDG-LIMIT values are changed over time from the old pic 99 format to the new comp field, as individual catalog records are accessed and updated.

However, if you revert to a previous release, the new-format System Catalog is not readable by the old version of the product. If you revert to a previous release, you can revert the System Catalog so that the system can use it.

To revert the catalog to GDG_LIMIT 99

  1. Backup your system catalog.
  2. Run the catalog scan utility mfcatrvt with no parameters.

    This identifies all GDGs where the LIMIT is greater than 99, or has been cycled more than 99 times.

  3. Run the catalog revert utility mfcatrvt with the command line parameter REVERT.

    This changes the comp value of the GDG-LIMIT field back to the original PIC 99 representation. Note that the process also converts values greater than 99 back to 99.

When this process completes, the System catalog is readable in older versions of COBOL Server.

Example

The following sequence of commands:
set MFSYSCAT=c:\estest\catalog.dat
mfcatrvt
generates the following output:
START mfcatrvt GDG LIMIT CHECKTEST101.GDGmfcatrvt GDG LIMIT
- completed normallymfcatrvt REVERT
mfcatrvt REVERT
START mfcatrvt GDG LIMIT REVERT
mfcatrvt GDG LIMIT - completed normally
Parent topic: Known Errors and Restrictions


JCL Utilities

  • Calling MFFJUXIT after a parsing error B539260 results in corrupting the JCL file name in -U-pc-fname. The file name is missing some leading characters.
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


Security Management

  • An enterprise server that is configured to use a Security Manager that uses the mldap_esm module (that is, using LDAP for security) cannot be started using a file repository, either by using the -m option to casstart and specifying a file path, or by running casstart when MFDS is not available. [542314]
  • A new facility called passtokens can be configured to let administrators move back and forth between MFDS and ESMAC without signing in each time they switch from one to the other. (This requires that MFDS and Enterprise Server use the same security configuration, and that the user has appropriate privileges.) However, the passtoken is created when the HTML page with the link to the other facility (for example, the MFDS "server details" page with the ESMAC link) is generated, and passtokens expire after a short time. If you wait too long before clicking the link to go from MFDS to ESMAC or from ESMAC to MFDS, you will be forced to sign on again. [543176]
  • Customers who use the audit feature of Enterprise Server security should be aware that we cannot enforce auditing for administrative changes to the security configuration (adding or removing users, changing permissions, etc). A user with sufficient privilege (an administrator) can disable auditing before performing other administrative changes, or use third-party tools to update the configuration in the ESM without using any Micro Focus tooling at all.[543360]
  • When external security is enabled for Enterprise Server, user credentials (username and password) have to be supplied to casstart in order to start the region. casstart uses those to do an ESF Verify and Auth to ensure that the user has authority to start the region. casstart also uses those credentials to bind to MFDS. A problem can arise because MFDS is a different security domain from Enterprise Server and may have a different security configuration, particularly if Enterprise Server is using an ESM (such as the eTrust one) that doesn't support MFDS. Consequently, administrators may have to define user accounts twice, once in the ESM used by Enterprise Server, and once in MFDS internal security (or a different ESM used by MFDS), in order to let those users start a region. [543472]
Parent topic: Known Errors and Restrictions


Spool File Format Change

The format of the spool record held in the MVS Spool file, mvsspl01.dat has changed.

After you install COBOL Server, the MVS Spool file conversion is handled automatically. The spool process:

  • Checks for the presence of an existing mvsspl01.dat file.
  • If found, automatically converts this file to a new-format mvsspl02.dat
  • Renames the old mvsspl01.dat file to mvsspl01.R1.

The mvsspl02.dat spool file is used in all subsequent processing.

However, if you revert to a previous release, the new format MVS Spool file records are not readable by an old version of the product. If you revert to a previous release, you can revert the new-format spool file to the old format.

To revert the mvsspl02.dat to mvsspl01.dat:

  1. Backup the existing mvsspl02.dat file.
  2. Set the MFSYSCAT Environment variable to the location of the System Catalog.
  3. Run the MVS Spool convert utility MFSPLRVT.

    This utility reads the records in the new format MVS Spool file mvsspl02.dat, converts then to the old format, and writes them to mvsspl01.dat. When this process completes, mvsspl02.dat is renamed to mvsspl02.r2.

When this completes, the MVS Spool file is readable in older versions of COBOL Server.

Example

The following sequence of commands:
set MFSYSCAT=c:\estest\catalog.dat
mfsplrvt
generates the following output:
REVERT SPOOL STARTED
REVERT SPOOL ENDED SUCCESSFULLY

The ctf tracing process has additional tracing functionality added so that information from the conversion is available in the event of problems. To enable this functionality, set the following line in the trace configuration file to enable trace events for both conversions: mvsspl01.dat to mvsspl02.dat and mvsspl02.dat to mvsspl01.dat:

mftrace.comp.mf.mvs.mvsspool#reformat = true

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 that 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 Micro Focus License Administration. The tool allows you to authorize, view and revoke licenses. You can set up your license locally or request a license from a central license server (if your site is using one).

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 Micro Focus License Administration 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.

See Managing Licenses for more details.

Parent topic: Welcome
Related concepts
Managing Licenses


Deploying COBOL Applications

Describes the concepts and tasks involved in deploying COBOL applications using COBOL Server.
  • COBOL Server
Parent topic: Micro Focus COBOL Server 2.2 for UNIX


COBOL Server

  • To install COBOL Server (or selected files)
Parent topic: Deploying COBOL Applications


To install COBOL Server (or selected files)

Note: The following applies to native COBOL only.

To install the full COBOL Server (recommended):

  1. Install COBOL Server either in same directory as your application or a separate directory, which is recommended if several applications will be sharing it. To install this, run the install file setup_cobol_server_2.2_platform.

    You can also install COBOL Server silently.

To install selected files (not recommended, but available for backward compatibility):

  1. Determine the files to ship.
  2. Extract the files in the COBOL Server install file, which is on your CD. To do this, run the executable file setup_cobol_server_2.2_platform.
  3. Copy the files that your application requires into same directory as your application, or if several applications will be sharing the files, copy them into a separate directory.
Parent topic: COBOL Server


Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

  • Enterprise Server configuration and administration
    Describes the processes for setting up, configuring, and maintaining an Enterprise Server installation. The information it contains relates to COBOL applications running as services that operate in an Enterprise Server environment.
  • Deploying and Configuring Modernized Applications
    Describes how to configure and administer modernized COBOL applications running in the Enterprise Server environment.
  • Enterprise Server Task Index
    Describes how to use Enterprise Server Administration to create, configure, and run an enterprise server, and perform other associated tasks.
  • Enterprise Server Reference
    Contains information on Enterprise Server configuration commands, error messages, user exits and switching modules.
  • Enterprise Server Security
    Contains information and procedures for all aspects of securing an Enterprise Server installation.
  • Enterprise Server License Messages
Parent topic: Micro Focus COBOL Server 2.2 for UNIX


Enterprise Server configuration and administration

Describes the processes for setting up, configuring, and maintaining an Enterprise Server installation. The information it contains relates to COBOL applications running as services that operate in an Enterprise Server environment.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Overview and Architecture
  • Configuration and Administration User Interface
  • Planning your Configuration
  • Configuring the Server Instance Environment
  • Configuring and Administering Enterprise Server Instances
  • Configuring Client-Server Communications
  • Monitoring Enterprise Server
  • User Exits for Request Handlers
  • Troubleshooting
  • Enterprise Server Administration Console Help Pages
Parent topic: Enterprise Server


Overview and Architecture

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section provides an overview of an Enterprise Server installation and its components, and describes the architecture.

  • Enterprise Server Overview
  • Enterprise Server Architecture
  • Enterprise Server Instance Architecture
  • The Micro Focus Directory Server
  • Service Execution Process (SEP)
  • Request Handlers
  • Communications Processes
  • Listeners
  • Implementation Packages
  • XA Resources
  • Enterprise Server Processes
Parent topic: Enterprise Server configuration and administration


Enterprise Server Overview

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server provides an execution environment for COBOL application programs. Within an Enterprise Server, you can operate a number of enterprise server instances. enterprise server instances provide session and state management for COBOL applications, as well as optionally interfacing with external resource managers to coordinate resource updates.

The type of applications you can run on an Enterprise Server installation fall into the following categories:

  • COBOL applications running as services

    A service can contain a number of operations. Clients that use these operations supply the required input, and the service returns the results.

Parent topic: Overview and Architecture


Enterprise Server Architecture

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An Enterprise Server installation consists of a Micro Focus Directory Server, and a number of enterprise server instances. An enterprise server instance provides a pool of pre-initialized service execution processes (SEPs), within which COBOL applications are executed.

When you install Enterprise Server, depending on the Micro Focus product, a number of enterprise server instances are automatically set up for you. You can create further enterprise server instances as required.

As an administrator, you log on to the Enterprise Server administration user interface operating on the Micro Focus Directory Server. From this user interface, you can configure installation-wide settings. From this user interface, you can also access the administration user interfaces for each enterprise server instance operating in the installation.

Parent topic: Overview and Architecture


Enterprise Server Instance Architecture

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following figure shows a high-level view of the enterprise server instance architecture and components.

Figure 1. Enterprise Server Instance Architecture

An enterprise server instance consists of some processes and an area used for inter-process communication.

As the COBOL applications run within their own address spaces, they are isolated from other programs executed within the enterprise server instance. Multiple execution processes enable concurrent processing of COBOL programs responding to client request messages.

The instance processes include a console daemon, server manager and communications process. These processes provide the following functionality:

  • The console daemon manages enterprise server instance processes and logs messages.
  • The server manager creates and manages the inter-process communication area and works in conjunction with the console daemon to provide process management.
  • The communications process receives incoming client requests and forwards them on to the appropriate services. It also receives the output from the request processing and sends it back to the clients. The requests can come from the following types of client:
    • Clients requesting a Web service. Requests from these clients arrive over HTTP as SOAP (Simple Object Access Protocol) messages.
    • J2EE clients requesting a service. Requests from J2EE clients arrive using a Micro Focus encoding and transport protocol.

All types of requests use TCP/IP as the underlying communications mechanism.

An enterprise server instance is created with one communications process, but you can add more to improve reliability and fault tolerance.

An enterprise server instance is created with two service execution processes (SEPs). A SEP is the process that actually executes the COBOL program that handles the client request. You can add more SEPs if the processing load requires it.

The inter-process communication area consists of a shared memory area that contains definitions of all the services that are available within the enterprise server instance. These definitions are located on the Directory Server. It sits outside the enterprise server instance, and can contain information for the enterprise server instances running in your installation. The inter-process communication area is also used to pass requests and responses between the enterprise server instance processes.

Parent topic: Overview and Architecture


The Micro Focus Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Micro Focus Directory Server (MFDS) is a process that maintains the Enterprise Server operating information. It maintains information on the following components:

  • Enterprise server instances and the services that are operating
  • Communications processes
  • Listeners
  • Request handlers
  • Implementation packages
  • XA resources

By default the Directory Server runs on the same machine as your enterprise server instances.

In addition to maintaining information on enterprise server instances, the Directory Server can also store information about CCI servers. These are servers that provide services using the Micro Focus Common Communication Interface (CCI), using the Directory Server as a naming server instead of registering with a CCITCP2 process. CCI servers are supported for backward compatibility:

  • Directory Server Information
  • Repository Statistics
Parent topic: Overview and Architecture


Directory Server Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Directory Server maintains information on all of the objects that it controls. These are:

  • Servers
  • Services
  • Communications processes
  • Service listeners
  • Request handlers
  • Implementation packages
  • XA resources
Parent topic: The Micro Focus Directory Server


Repository Statistics

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Some items of information about the repository appear on the Statistics page:

  • Total count – the total number of objects currently in the repository
  • Repository status – the current status of the repository, for example, when Directory Server started and how many objects were loaded into the Directory Server from the repository
  • Repository location – the directory where the repository is located. By default this is $COBDIR/etc/mfds.

You can also find the repository location by using the /m option of the mfds command-line utility (e.g. mfds /m).

Parent topic: The Micro Focus Directory Server


Service Execution Process (SEP)

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An enterprise server instance can run a number of SEPs, depending on the functionality it provides. When a SEP has finished processing a request, it becomes available to process other requests as they are generated. A SEP contains the following components:

  • Application container

    The COBOL run-time system adapted to operate in the Enterprise Server environment. Within a SEP, an application runs inside an application container.

  • Transaction management component

    Manages transactions for container-managed services, that is, it coordinates COMMITs and ROLLBACKs.

  • Request handler

    Decodes requests that are received. There is a Micro Focus request handler for each type of client request that Enterprise Server can handle. The request handler maps the output parameters into a form the client will understand.

    There are request handlers for the SOAP protocol and for the Micro Focus binary protocol. You can configure user exits to customize the request provided for the SOAP protocol.

  • Resource manager interface

    Handles requests for resources such as database and file access.

The processing of a request proceeds as follows:

  1. An enterprise server instance's communications manager receives a client request. The request is queued within the shared memory area and is scheduled for execution.
  2. When a SEP becomes available, it starts processing the request: it calls the application container.
  3. The application container then calls a request handler to decode the received request.
  4. Once the transaction or application has finished processing the request, the application container calls the request handler to map the output parameters into a form the client will understand.
  5. The application container then passes the response to the communications manager, which sends it back to the client.
Parent topic: Overview and Architecture


Request Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A handler, or request handler, is a program that receives a client request for access to the service, and translates the request into a form that the service can understand. After the service has completed its task, the request handler translates the output back into a form that the client can understand, then passes the output to the client, via the communications process.

We provide request handlers for the SOAP protocol and for the Micro Focus binary protocol. You can customize the request provided for the SOAP protocol using user exits.

Parent topic: Overview and Architecture


Communications Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Communications processes are responsible for listeners. When you add a new enterprise server instance, it is created with one communications process, containing listeners for the two system services. You then add further listeners as required to deal with the expected workload of the enterprise server instance. Once you have the process defined as you want, you can create additional communications processes by copying the existing one. The advantages of having more than one communications process are:

  • The enterprise server instance is more robust in the event of communications failures. If one communications process encounters a problem, the others can continue to receive and process client requests and send back the replies.
  • The enterprise server instance can handle more client requests, because communications processes use a threaded architecture, and more communications processes means that more threads are available.
Parent topic: Overview and Architecture


Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A listener object contains a network address that accepts incoming client requests on behalf of services. A service can have multiple listeners, and a listener can accept client requests on behalf of multiple services.

You can configure a listener to use SSL (Secure Sockets Layer), a facility for secure, encrypted communication and checking online identities.

Each listener is associated with a connector. This is software that can process the type of requests the listener handles.

Enterprise Server comes with several connectors, including:

  • The soap connector, which handles both Web Services SOAP requests and the Micro Focus Binary Protocol used for J2EE requests.
  • The http-switch connector, which provides simple web server capabilities and is used for service deployment.
  • The http-echo connector, which responds to HTTP requests with a short HTML reply and can be used for connection testing.
Parent topic: Overview and Architecture


Implementation Packages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An implementation package object contains information about the COBOL application that provides the service. A package is associated with an interface definition table (IDT), which contains the information that allows a client request to be mapped onto a COBOL program interface.

Parent topic: Overview and Architecture
Related information
Services, Packages and Request Handlers


XA Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An XA Resource object contains information about an XA-compliant database manager required to provide database access to one or more container-managed services.

Parent topic: Overview and Architecture
Related information
Resource Management
Resource Managers


Enterprise Server Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CASCD - Region Console Daemon
CASCD manages region processes and console log messages. There is one of these console daemon process for every region. It is started by the casstart process.

CASCD is the parent of all other processes that run for the lifetime of the region. If it detects they have died, it informs CASMGR and restarts them.

Responsibities:

  • Starting processes
  • Monitoring started processes
  • Informing Server Manager of any process termination
  • Console Messages
CASMGR - Region Server Manager
CASMGR is started by the CASCD process, and works in conjunction with the Console Daemon to provide process management. There is one server manager process per region, represented by a DCA control block in shared memory.

Responsibilities:

  • Creates and manages the IPC area (shared memory) based on configuration data from MFDS
  • Controls the system state of Enterprise Server
  • Participates in error recovery processing
  • Monitors region state for timeouts and deadlocks
CASTSC - Region Temporary Storage, Channels and Containers Control (TSC)
CASTSC controls temporary storage, channels, and containers. There is one process per region. It is started by CASCD.

Responsibilities:

  • Historical Statistics Facility
  • Auxiliary trace logging
  • Distribution of system events to interested parties
MFCS - Micro Focus Communication Server

MFCS is the region communication component which handles the communication between clients and the Enterprise Server. There can be one or more communications servers per region depending on capacity needs.

MFCS is started by CASCD and contains the Web Services listener.

It is represented by a TCTS control block in shared memory.

Parent topic: Overview and Architecture


Configuration and Administration User Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section introduces the Enterprise Server Administration web interface and the configuration process. You can use the administration interface to configure, monitor, and control enterprise server instances locally, across the Internet, or on your intranet, from a computer that has any of the following browsers installed:

  • Internet Explorer V6.0 or greater
  • Netscape V6.0 or greater
  • Mozilla V1.3 or greater
Note: By default Directory Server uses port 86. If you have an active firewall on the Directory Server machine, you need to make sure that it is configured to allow access to this port.
  • About the Enterprise Server Administration User Interface
  • User Interface Tables
  • Navigation
  • Accessing the Enterprise Server Administration UI
Parent topic: Enterprise Server configuration and administration


About the Enterprise Server Administration User Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you access the Enterprise Server user interface, the Home page is displayed. What you can see depends on your access permissions, set by your login ID.

Menus

The Enterprise Server Administration menus appear in a panel on the left side of the page. The menu options are grouped under headings, such as Actions. You see only the menu options that are appropriate to your permission level. Some Enterprise Server Administration; actions are available as push buttons on tables.

Status line

The status line appears towards the top of the page, under the Enterprise Server Administration heading. This line provides information about the status of the Directory Server. If the information is an error message, it appears in red.

Enterprise server instances

Information about the enterprise server instances is presented in tables on the user interface. You can modify the level of information displayed on the home page by using the the expand button and the contract button buttons in the top left-hand corner of the servers table.

Most tables contain one or more Edit buttons, which you can click to go to a page to update the selected object's attributes, and an Add button, which you can click to go to a page where you can add an object of that type.

Refreshing a page

Many pages contain a Refresh button. Click this after you have performed an action that should be reflected in the contents of that page's table. For example, if you have just added a server, click Refresh on the Home page, and the details of the new server will appear in the servers table. Some pages also include an Auto-refresh interval field that enables you to specify the interval (in seconds) between automatic refreshes. The default (and the minimum) is 10 seconds; a blank space means no automatic refresh.

Parent topic: Configuration and Administration User Interface


User Interface Tables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Information about the objects in the Directory Server is presented in tables. The table that you see on the Home page after you have logged on presents information about the servers in the Directory Server repository. You can modify the level of information displayed on the home page by using the the expand button and the contract button buttons in the top left-hand corner of the servers table

The servers table has a number of Details push buttons, which you can click to go to a page with more detail on that particular type of object.

In the server table some columns are white while others are beige. Information in the white columns applies to both enterprise servers and CCI servers, while information in the beige columns applies only to enterprise servers.

As soon as you select a server to edit, or one of the other tables to view, such as the service table, the page changes to a tabbed format, enabling you to switch between communications processes, services, request handlers and implementation packages. The figure below shows the Edit Server page. The numbers in parentheses after the tabs on the top row indicate how many objects of that type are registered with the server.

Figure 1. Edit Server Page Showing Tabs
Edit Server Page Showing Tabs

Most tables also contain one or more Edit buttons, which you can click to go to a page where you can update the selected object's attributes, and an Add button, which you can click to go to a page where you can add an object of that type.

Parent topic: Configuration and Administration User Interface


Navigation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server Administration provides two sets of facilities, each with its own mode of navigation:

  • You perform various administrative tasks, such as saving and restoring Directory Server information, and creating new users, by selecting items from the menu in the left-hand panel. What you can select depends on your permission level.
  • You work with objects in the repository by clicking buttons in the main part of the page, usually in the table currently being shown. For example, if you want to add a new request handler, you need to:
    1. Click Details against Request Handlers in the table of servers on the Home page, to see the table of request handlers.
    2. Click Add in the bottom left-hand corner in the request handlers table, to reach the Add Request Handler page.

You can always return to the Home page wherever you are by clicking Home at the top of the menu in the left-hand panel, or upwards-pointing arrow in the top left-hand corner of the server details page or any of the object details pages.

Note:

We recommend that you do not use the Back button on your Web Browser tool bar to return to the previous page, as doing this might resubmit an administration request that is no longer valid.

Parent topic: Configuration and Administration User Interface


Accessing the Enterprise Server Administration UI

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Providing the MF Directory Server is running, you can access the user interface directly from a web browser:

  • Open a Web browser and enter the URL http://targetname:86. Where targetname is the machine on which Enterprise Server Administration is running. For example, if Enterprise Server Administration is running on your local machine, enter http://localhost:86.

    Enterprise Server Administration opens with the Home page. If user access is restricted, you must logon before you can access any other features.

If you have Visual COBOL installed, there are two alternative methods of accessing Enterprise Server Administration on your local machine:
  • Click > Configuration > Enterprise Server Administration

If you see the message "The Page cannot be displayed", it might be that the Directory Server has stopped and needs restarting.

  • Displaying Server Information
  • Refreshing a Page
Parent topic: Configuration and Administration User Interface
Parent topic: Enterprise Server Task Index


Displaying Server Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To see the information about servers managed by the Directory Server, access the server table on the Enterprise Server Administration Home page.

Note: The server information displayed depends on the user and group permission that are set. For example, if you have not been granted "read" permission for a particular server, you will be unable to view it in the list.

The server table is available in two modes, summary and expanded. When you first start Enterprise Server Administration, it is shown in summary mode. You can switch to expanded mode by clicking the icon at the top left-hand corner of the table.

Figure 1. Server Table in Expanded Mode
Server Table in Expanded Mode
Parent topic: Accessing the Enterprise Server Administration UI
Parent topic: Monitoring the Directory Server


Refreshing a Page

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Many pages contain a Refresh button. Click this after you have performed an action that should be reflected in the contents of that page's table. For example, if you have just added a server, click Refresh on the Server Information page, and the details of the activity are updated.

You can also configure the ESMAC pages to automatically refresh. To do this:

  1. In the Interval field, which is adjacent to the Refresh button, enter the number of seconds to wait between each refresh. This must be a number greater than 10.
  2. Click the Refresh button.
Parent topic: Accessing the Enterprise Server Administration UI
Parent topic: The ESMAC User Interface


Planning your Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes the issues and performance considerations that affect how you will configure Enterprise Server after you have installed it.

  • Introduction
  • Security Options
  • Setting up the Environment
  • Firewall configuration
  • About Communications Processes
  • Deployment Services and Listeners
  • Enterprise Server Instance Configuration Issues
  • Performance Considerations
Parent topic: Enterprise Server configuration and administration


Introduction

Restriction: This topic applies only when the Enterprise Server feature is enabled.

After installation and before users start working with Enterprise Server, you need to:

  1. Decide on a user account strategy and implement it. Set up the user environment.
  2. Based on your security requirements, configure your security options.

    This is a complex subject, and is covered in a separate section.

  3. Set configuration options for the Directory Server.
  4. Set configuration options for your enterprise server instances.
Parent topic: Planning your Configuration


Security Options

Restriction: This topic applies only when the Enterprise Server feature is enabled.

By default, an application running in an enterprise server instance has the access permissions of the login ID that started the session under which it is running.

You can configure security managers to control access to applications and resources, regardless of the access level that the operating system allows.

We recommend that you carefully consider the security options that you require and configure your system appropriately.

Note: To ensure system robustness, you should use the same security configurations for both the MF Directory Server and the enterprise server instances that the MF Directory Server controls. If you do not, there is a risk that you will configure a system where an application has insufficient rights to access the resources that it needs.

Details on securing your installation, and the resources invoked from within your applications are included in a separate section of the help: Securing an Enterprise Server Installation.

  • About Securing an Enterprise Server Installation
Parent topic: Planning your Configuration


About Securing an Enterprise Server Installation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You use the Enterprise Server security facility to implement user authentication, and to control access to the applications and resources that a system uses.

You control access to Enterprise Server administrative features and application resources through the use of security managers, sometimes referred to as external security managers (ESMs). Through the use of these security managers, you can implement measures such as verifying users against the operating system configuration or incorporating an LDAP repository into your Enterprise Server security.

Securing an installation involves securing access to the following system components:

  • The Directory Server (MFDS)

    The Directory Server maintains records of system components and their configurations. You use the Enterprise Server Administration user interface (ESMAC) to create and modify these configurations. Securing the Directory Server controls who can configure the system.

  • Enterprise Servers

    Enterprise Servers use the application's program files, data files, and other items that a system uses while operating.

  • Inter-system communications

    You can configure SSL links between components to secure these communications. This is covered in another part of the help.

Note: It is possible to apply different security configurations to the Directory Server and the Enterprise Servers. This can cause problems during operation however. For example an administrator can have MFDS access permissions to configure a resource, but if the enterprise server does not have access permissions to use the resource, it cannot be used during operation. The safest thing to do is to apply the same security configuration to the Directory Server and the Enterprise Servers it controls.
Parent topic: Security Options
Parent topic: Architecture and Overview


Setting up the Environment

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before you can do any configuration, you need to set up the environment then start the Directory Server.

You need to

  • Provide a Process User ID, if this was not done at installation time.
  • Set some environment variables

The command to start the Directory Server is mfds. You need to log in as root before you run mfds.

The commands to set up the environment and start the Directory Server can be inserted into your startup shell script; then the Directory Server will be started automatically when the machine is started. The mfds command must be inserted after the command to start up TCP/IP, because the Directory Server needs TCP/IP to be running. If the command has been added to your startup shell script you would normally need to start the Directory Server only if you had shut it down since you started the machine.

  • Process User ID
  • System-wide Environment Variables
Parent topic: Planning your Configuration


Process User ID

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Process User ID is the UNIX user ID under which all Enterprise Servers started from Enterprise Server Administration run. You need to supply a Process User ID because the Directory Server itself has to run as root, and without specifying a different user ID the enterprise servers started from the Directory Server would also run as root. The Process User ID is normally supplied at installation time by the installer. If it was not supplied at installation time, you have to supply it before you can use Enterprise Server. You should choose a user ID that has permission to do everything that the applications you plan to run in Enterprise Server need to do, for example, access data files. This user ID should already exist on the system. To provide a Process User ID, you must run the command casperm. This command also gives you the opportunity to configure some other aspects of Enterprise Server.

Once you have configured Enterprise Server and the Directory Server, you can change the Process User ID on the Configuration Options page. If you change it you must supply a user ID already known to the UNIX system.

Parent topic: Setting up the Environment


System-wide Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You need to set the following environment variables that apply to all activities that take place in Enterprise Server:

  • COBDIR. Specifies the directory that contains Enterprise Server
  • PATH. Specifies the directories to be searched by all UNIX programs, including the run-time system, when finding executables to be run
  • LD_LIBRARY_PATH, LIBPATH or SHLIB_PATH, depending on your UNIX system. Specifies the directory or directories for the UNIX system, cob and the run-time system to search for shared libraries and callable shared objects.

If you want to do any database access from within Enterprise Server you need to add the necessary libraries to the PATH environment variable and to the LIBPATH, SHLIB_PATH or LD_LIBRARY_PATH environment variables, depending on your UNIX system. For full information about setting the environment up for database access see the documentation supplied by your database vendor.

Parent topic: Setting up the Environment


Firewall configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have an active firewall on the machine that is running your Directory Server and enterprise server instances, and you want remote clients to be able to connect to them, you must ensure that the firewall allows access to the ports that you are using.

For example, Directory Server is configured, by default, to use port 86. Your must configure your firewall to allow TCP and UDP access to this port. Similarly, the default enterprise server instance, ESDEMO, has a Web Services and J2EE listener that uses port 9003. For remote clients to be able to submit requests to this listener, your firewall must permit access to this port.

We recommend that, if you want remote users to access Enterprise Server functionality through the firewall, you use fixed port values so that you can control access via these.

Note: If you are using Microsoft Windows XP and have installed Service Pack 2, you might find that you cannot see certain Enterprise Server Administration pages, because of firewall restrictions. To get round this, you need to enable access to the ports you are using, for example, 86 for the Enterprise Server Administration Home page and 9003 for the default enterprise server, ESDEMO. Use the Windows Security Center to do this.
Parent topic: Planning your Configuration


About Communications Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Communications processes handle communications between clients and the enterprise server instance, and consist of a number of service listeners. When an enterprise server instance is created it contains one communications process. If there is a communications failure for any reason, the enterprise server instance cannot process any work until the communications process is restarted. So, to improve the ability of an enterprise server instance to withstand communications failures, you can create one or more additional communications processes per enterprise server instance. You create an additional communications process by copying an existing one. The new communications process is an exact clone of the original, except that any fixed port numbers are not cloned. The first communications process in a newly created enterprise server, Communications Process 1, contains a Web Services and J2EE listener and a Web (deployment) listener. If you are creating a new enterprise server, you might want to modify this communications process definition before you copy it, depending on the particular workload you have planned for the server.

For fault tolerance you need at least two communications processes. You might need more than two to overcome operating system thread limits. The maximum is 32.

Parent topic: Planning your Configuration
Parent topic: Configuring the Server Instance Environment
Parent topic: Configuring Client-Server Communications


Deployment Services and Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.

After installation, the enterprise server instance ESDEMO has a default deployment service named "Deployer". You can modify this deployment service or create additional deployment services with different configurations. You can also add deployment services to enterprise servers that you create.

The Deployer service uses a listener called Web, which uses the http-switch connector. If you modify the Deployer service, you will probably need to change the configuration of the Web listener too. You can also create your own listeners for use with deployment services.

  • Deployment Services
  • Deployment Listeners
Parent topic: Planning your Configuration


Deployment Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

All deployment services must have their Service Class attribute set to 'MF deployment'. They must be associated with a listener that uses the conversation type 'Web'.

The configuration information for a deployment service looks like this:

[MF client]
 scheme=http
 URL=virtual-directory-name-1/mfdeploy.exe/virtual-directory-name-2
 accept=application/x-zip-compressed

where virtual-directory-name-1 specifies the directory that holds the deploy program, mfdeploy.exe, and virtual-directory-name-2 specifies a directory to contain deployed services.

The values for the scheme and accept parameters must not be changed, but when you are creating a new deployment service you can omit them, as these are the defaults.

The settings for the Deployer service of ESDEMO are:

[MF client]
 scheme=http
 URL=/cgi/mfdeploy.exe/uploads
 accept=application/x-zip-compressed

The configuration of a deployment service must match the configuration of the listener for the service. The URL parameter must specify the same virtual directory name for the location of the mfdeploy.exe program as the listener uses. You can change the virtual path to receive deployed services to any virtual directory name configured for the listener.

For example, if the listener's configuration was:
[virtual paths]
 <default>=/dev/null
 studioenterpriseedition=<ES>/bin
 project1=home/development/project1
 project2=home/development/project2
then you might create a deployment service named "project1" with this configuration:
[MF client]
 scheme=http
 URL=/studioenterpriseedition/mfdeploy.exe/project1
 accept=application/x-zip-compressed

and services deployed using the "project1" service would be stored under /home/development/project1. You could create a similar service for project2.

Note that the deployment directory must have a .mfdeploy file. Copy the .mfdeploy file from $COBDIR/deploy and modify it as necessary.

Parent topic: Deployment Services and Listeners


Deployment Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The configuration information for a deployment listener consists of the section name "[virtual paths]" followed by a list of URL top-level directories and the paths they will be converted to. For example, the Web listener used by ESDEMO's Deployer service looks like this:

[virtual paths]
 cgi=<ES>/bin
 uploads=<ES>/deploy
 <default>=/dev/null

The "cgi" virtual path is used to specify the location of the mfdeploy.exe program that receives the COBOL archive file being deployed, and the "uploads" virtual path tells mfdeploy.exe where to create the directory for the uploaded COBOL archive file.

mfdeploy.exe is located in $COBDIR/bin.

On UNIX platforms, the special token "<ES>" is translated into the directory named by the COBDIR environment variable, which should be the COBOL Server installation directory. For example, if $COBDIR is /opt/microfocus/VisualCOBOL, then "<ES>/deploy" becomes /opt/microfocus/VisualCOBOL/deploy, the default deployment directory.
Note: On UNIX platforms, the value of $COBDIR used by Enterprise Server is the one set for the Directory Server process, which normally runs as a system daemon.

Only the first directory in the URL specified by the client performing the deployment is checked against the list, and the entries in the list have to be just a single directory name.

The "<default>" directory is used if the first directory in the URL specified by the client doesn't match any of the entries in the list. The default directory must be one that does not exist, so that when the communications process translates the URL into a full path, the request will fail. This stops any attempt by a client to browse arbitrary directories on the machine. You don't need to specify a default directory, since the communications process uses a safe default anyway.

Here is another example:

[virtual paths]
 <default>=/usr/web
 docs=/usr/web/documents
 images=/home/media/images

With this configuration, the URL http://host:port/docs/a.html will return the file /usr/web/documents/a.html, and the URL http://host:port/images/gif/b.gif will return the file /home/media/images/gif/b.gif.

Parent topic: Deployment Services and Listeners


Enterprise Server Instance Configuration Issues

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can configure various attributes of an enterprise server instance, for example how much memory is available to it, how many service execution processes it starts up with, what information is traced. Most of these options are fairly straightforward; in any case detailed advice on these options is available in the help for the Add Server and Edit Server pages.

An enterprise server instance and the objects it contains (services, listeners, etc) each have a specific Configuration Information field, accessible on the Add and Edit pages for each type of object. Entries in the Configuration Information field use the .ini file format, with section names in square brackets followed by name/value pairs:

[ASection]
name1=value1
name2=value2

Most settings are case-insensitive except the names of virtual paths for the Web listener, which are case-sensitive, and on UNIX, settings for environment variables (in [ES-Environment]) and values that include file or directory names are case-sensitive.

  • Shared Memory Area
  • Shared Memory Cushion
  • Number of Service Execution Processes
Parent topic: Planning your Configuration


Shared Memory Area

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The shared memory area is an area of memory where an enterprise server instance stores all the information it needs to run (see the section COBOL Server Architecture in the chapter Introduction). The shared memory area is measured in pages of 4KB each. The shared memory area has to be big enough to contain all the definitions of the objects in the server, and all the current client requests. If you run out of shared memory while the server is running, the performance of the enterprise server instance will be significantly affected and this could prevent client requests from being processed.

Use the calculation described in this section to estimate the number of shared pages to allocate to an enterprise server instance.

Actual requirements vary according to the nature of the workload, but you are advised to allow a generous safety margin. Enterprise Server optimizes the use of the shared memory resource by minimizing the number of physical pages used at lower than maximum processing volumes.

Perform the calculations in the middle column of the table below and enter the result of each calculation in the right-hand column. The sum of these answers is the minimum number of bytes required for the shared memory. Divide this number by 4096 and round up to a whole number to get a figure for the number of shared pages needed.

Item | Calculation | Result
Overhead | Fixed size | 8192
Shared memory area management | Shared memory area size / 4096 |
Trace | If auxiliary trace not active: Number of entries x 24 |
Trace | If auxiliary trace active: Number of entries x 24 x 11 |
Local trace | Number of service execution processes x number of entries x 24 |
Services | Number of services x (128 + service-name-length) |
Service execution processes | Number of service execution processes x 144 |
Request handlers | Number of request handlers x (128+handler-name-length) |
Packages | Number of packages x (128+IDT-name-length + application-path-length + module-name-length) |
Resident IDTs | Number of resident IDTs x IDT-length |
Client requests | Number of client requests being processed at any one time x (256 + average size of client request) |
Clients | Peak number of concurrent clients x 64 |
Access Control Environment Elements | Peak number of signed-on users x 428 The number of signed-on users should include the 4 default users used by the system. |
Total |  |

where:

service-name-length | is the length of the service name
handler-name-length | is the length of the name of the request handler
IDT-name-length | is the length of the IDT name
application-path-length | is the length of the path to the COBOL application in the package
module-name-length | is the length of the name of the module containing the application
IDT-length | is the size of the IDT file for a package
Parent topic: Enterprise Server Instance Configuration Issues


Shared Memory Cushion

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The shared memory cushion is part of the shared memory area. Its function is to handle short-term high demands on the server. When an enterprise server instance starts, the shared memory cushion is not available for use, and it is never used by incoming client requests. It is used only when a response needs to be passed back to a client, and there is insufficient free memory in the main area to handle the response.

The shared memory cushion is also measured in pages of 4KB each. Set the shared memory cushion to 10% of the size of the shared memory area.

Parent topic: Enterprise Server Instance Configuration Issues


Number of Service Execution Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When an enterprise server instance is created it contains two service execution processes (SEPs). SEPs process incoming client requests. When a response has been returned to a client, the SEP becomes available again to handle another request. If all the SEPs are busy handling requests, incoming requests must wait for one to become free. The number of SEPs in an enterprise server instance impacts performance. The kind of impact depends on a number of variables. You will need to experiment to find out the optimum number of SEPs in any particular enterprise server. For more advice see the section Performance Considerations .

You can change the number of SEPs in an enterprise server while it is running, although any change you make has an effect only until you stop the server. At this point the number of SEPs reverts to the value you set when you added the server or edited the server details.

Parent topic: Enterprise Server Instance Configuration Issues


Performance Considerations

Restriction: This topic applies only when the Enterprise Server feature is enabled.

How you configure an enterprise server instance for performance depends on a number of factors. One obvious factor is the expected workload of the server. You need to consider the frequency with which client requests arrive, and the required speed of response to those requests.

Two more factors are the type of services that run within the server and the type of requests for the services. Services can be categorized as I/O-bound or CPU-bound, while client requests can be categorized as short-running or long-running.

  • I/O-bound Services
  • CPU-bound Services
  • Short-running Client Requests
  • Long-running Client Requests
Parent topic: Planning your Configuration


I/O-bound Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Services that perform a lot of I/O requests are often dormant while they are running, while they wait for the responses to their requests. However, processing I/O requests can sometimes make considerable demands on the CPU. You need to consider whether you might need more service execution processes for this type of service.

Parent topic: Performance Considerations


CPU-bound Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Services that do not perform any I/O requests (or very few) are usually constrained by the use they make of the central processor. With CPU-bound services, fewer service execution processes usually work better, because the central processor switches between the running tasks, and this is an overhead.

Parent topic: Performance Considerations


Short-running Client Requests

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Short-running client requests are requests where there is just one interaction between the client and the service; the client request arrives, the service runs, and a response is returned to the client. Requests from Web services clients are always short-running.

With short-running requests, you only need to consider whether or not the the service itself is I/O-bound or CPU-bound.

Parent topic: Performance Considerations


Long-running Client Requests

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Long-running client requests are requests where the same client can make repeated requests of a service and needs data to be preserved between invocations of the service. In Java terms, they are stateful requests. So if the client is a stateful Java bean running in an application server such as WebLogic or WebSphere, the service will run for as long as the bean runs. In these circumstances, you need more service execution processes, even if the service itself is CPU-bound rather than I/O-bound.

If the enterprise server instance detects that the request is stateful, a new service execution process is started automatically. Dynamic growth of service execution processes consumes machine resources and can affect the performance of the enterprise server. We recommend that, unless your application design actually requires stateful interaction, you keep these types of request to a minimum.

Parent topic: Performance Considerations


Configuring the Server Instance Environment

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use the Configuration Information field on the Add Server and Edit Server pages for configuration data specific to each enterprise server instance. This field can contain the following section:

[ES-Environment]

Settings in this section are added to the environment of programs running under this enterprise server. You can use it to set arbitrary environment variables required by your programs, or to set system or COBOL run-time variables such as PATH and COBPATH. On UNIX, settings in this section are case-sensitive.

You can also use the Configuration Information field on the Add Server and Edit Server pages to set parameters for communications processes belonging to that enterprise server instance. Communications process settings in the server object apply to all of the communications processes for that enterprise server instance. To set parameters for only one communications process, use the Configuration Information field on the Add Communications Process or Edit Communications Process pages.

In order to add comments within your configuration information, prefix each line of text with the number sign (#).

  • Configuring Environment Variables
  • About Communications Processes
  • Configuring Fileshare
  • Using XA-Compliant Resources
Parent topic: Enterprise Server configuration and administration


Configuring Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

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.
  • How Enterprise Server uses Environment Variables
  • Setting Environment Variables
  • Environment Variables by Groups
  • Environment variables in alphabetical order
Parent topic: Configuring the Server Instance Environment


How Enterprise Server uses Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An enterprise server instance's environment depends on the method you use to start the server instance:

  • When you start an enterprise server instance from the Enterprise Server Administration user interface, it inherits its environment from the Directory Server.
  • When you start an Enterprise Server instance from the command line using the casstart command, it inherits its environment from that command-line shell.

This means that all the environment variables that you need to run your servers' workload, including directory settings for third-party software, can be set in the session where you start the Directory Server. If Directory Server is running as a Windows service, it will have the system environment.

You can set environment variables for an enterprise server instance in Configuration Information on the Add Server or Edit Server page. These apply to all services that run in the server.

Any environment variables set at the service level when the service was created using the Interface Mapping Toolkit override the settings at the server level.

The format for environment variables is

[ES-Environment]
environment-variable-name=environment-variable-setting

use a colon to separate elements within the string. For example:

[ES-Environment]
COBPATH=/home/adirectory:home/anotherdirectory
Note: We recommend that you do not set the COBDIR environment variable for an enterprise server instance, especially on UNIX. This is because $COBDIR is used to point to the product location. The results of setting $COBDIR are undefined. Use the COBPATH environment variable if you want to specify the location of service programs at the enterprise server level. If you do set the COBPATH environment variable at enterprise server level, you also need to specify "$COBPATH" in Package Path in the Add Package or Edit Package page for services that should be located using COBPATH.

When you specify an environment variable, you can use the resolved value of another already-created variable as part of the environment variable value. To do this, prefix the environment variable you want to include with a dollar ($) sign, for example:

FILEROOT=/home/data
FILEA=$FILEROOT/mydata.dat

This resolves to /home/data/mydata.dat.

If you want to include a dollar sign in an environment variable value as part of the actual value, rather than as an indicator that another environment variable is being referred to, you can enable the dollar sign character to be escaped by inserting a backslash (\) character, for example:

FILEA=\$\$fsserver1/mydata.dat

This resolves to $$fsserver1/mydata.dat

Because of the function of the backslash (\) character as an escape character, if you want the value of an environment variable to be a UNC path (e.g. \\server\volume\directory\filename), be sure that it starts with four backslash characters - \\\\server\volume\directory\filename - rather than two. Each pair of backslash characters resolves to a single character, yielding the correct two-character sequence as a final result.

Parent topic: Configuring Environment Variables


Setting Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use Enterprise Server environment variables to configure a wide range of settings to be used by enterprise server instances. You can set environment variables to apply to all server instances running on an installation, or to apply to specific server instances only. You can also use environment variables to allocate datasets.

  • Environment variables set at the Micro Focus Directory Server (MFDS) level apply to all Enterprise Server instances controlled by MFDS.
  • Environment variables set at the enterprise server instance level apply to the instance only.

You can set environment variables from the Enterprise Server Administration user interface, or from the command line.

  • Setting Environment Variables for Micro Focus Directory Server
  • To Set Environment Variables from the User Interface
  • To Set Environment Variables from the Command Line
  • To Specify Dataset Allocation Using Environment Variables
Parent topic: Configuring Environment Variables


Setting Environment Variables for Micro Focus Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you set environment variables for a Micro Focus Directory Server (MFDS), the environment variables apply to all server instances that the MFDS controls.

Note: Environment variables set at the enterprise server instance level override any corresponding environment variables set at the MFDS level.

Under UNIX, you configure the environment variables in the command shell from which you start MFDS. For example:

  1. Start a command shell.
  2. Set the environment variables that you want. For example, to set that the Enterprise Server instance uses the EBCDIC character set, use the following command:
    export MF_CHARSET=EBCDIC
  3. From the command shell, use the mfds command to start MFDS.
Parent topic: Setting Environment Variables


To Set Environment Variables from the User Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

From the Enterprise Server Administration user interface, you can set environment variables to apply to each server instance that the interface displays.

  1. From the Enterprise Server Administration page, click the Edit button that corresponds to the enterprise server instance to configure.
  2. Select the Server > Properties > General tabs.
  3. In the Configuration Information text box, type: [ES-Environment]
  4. Enter the environment variable information to configure, using a separate line for each variable to configure.

    Enter the information in the form:

    <variable name>=<value>

  5. Click OK to apply the settings to the server instance.

For example, to configure that an enterprise server instance uses the EBCDIC character set, you would enter the following:

[ES-Environment]
MF_CHARSET=EBCDIC
Parent topic: Setting Environment Variables


To Set Environment Variables from the Command Line

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before starting an enterprise server instance from the command line, you can set environment variables to apply to the enterprise server instance.

From the command line, set the environment variables:

For example, to set that the enterprise server instance uses the EBCDIC character set, use the following commands:

export MF_CHARSET=EBCDIC

or enter the casstart command to start the enterprise server instance.

Parent topic: Setting Environment Variables


To Specify Dataset Allocation Using Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To configure datasets, you can specify the full path for each dataset accessed by Enterprise Server. However this is cumbersome and can make it difficult to move between test and production environments that have different directory structures.

To reduce the effort required when the system uses large numbers of data files, you can set environment variables to define the datasets that an Enterprise Server instance uses:

  1. From the Enterprise Server Administration page, click the Edit button that corresponds to the Enterprise Server instance to configure.
  2. Select the Server > Properties > General tabs.
  3. In the Configuration Information text box, type: [ES-Environment]
  4. Configure the datasets to use with the ENVIRONMENTVAR=path syntax where:
    • ENVIRONMENTVAR is the name of the environment variable you are creating
    • path is the full path, including the drive letter, to the dataset.

    You can create as many environment variables as you need to cover all of the paths you want to specify.

  5. When you have defined the datasets, click OK. The settings are applied to the Enterprise Server instance.
  6. In the catalog, when allocating datasets using the %PCDSN option to specify a physical file, you can substitute an environment variable that you defined to represent the path to the file. Prefix environment variable names with a dollar sign ($): $ENVIRONMENTVAR
Parent topic: Setting Environment Variables


Environment Variables by Groups

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following sections list the environment variables by functional group.

Note: The Environment Variables: Alphabetical Order topic contains the values for most environment variables.
  • CCI Environment Variables
    Lists environment variables that relate to CCI.
  • Enterprise Server Communications Environment Variables
    Environment variables for configuring the input and output and the display.
  • File Handling and Dataset Environment Variables
  • Input, output and display environment variables
  • Security and Auditing Environment Variables
  • SORT Engine Environment Variables
  • Tracing and Debugging Environment Variables
  • Reserved Environment Variables
Parent topic: Configuring Environment Variables


CCI Environment Variables

Lists environment variables that relate to CCI.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Generic environment variable | Description
CCITIMEOUT Allows the specification, in tenths of seconds, of the maximum time out period that will be used with any CCI based application, such as Drag and Drop, SourceConnect, FileShare or the Compare and Syncronisation Monitor. The default is 2 minutes (1200), and the maximum value that can be used is 2,147,483,647. For example to set this value to 4 minutes:

SET CCITIMEOUT=2400

CCIERRLOG | Specifies the output location and filename of ccierr.log content which tracks first-instance errors reported from the operating systems. CCIERRLOG overrides any entries found in CCI.INI, where the syntax and content is explained in detail.
CCITRACE Specifies the level of CCI tracing

Values

Filename for and trace output and the trace options. The trace options are as follows:

Note: In all options, / or - must prefix the option. That is, /OFF is the same as -OFF.
  • /OFF

    Switches all CCI tracing off regardless of CCI.INI settings.

  • /N

    Do not trace any user data in the output. Only trace system activity.

  • /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.

  • /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

    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.

TCP/IP specific variables | Description
CCITCP2 | Locates the TCP/IP registration program. Values: The hostname or the IP address of the machine hosting the CCITCP2 registration program.
CCITCP2_PORT | The port that is being used for the registration process. Values: The port on which the CCITCP2 registration program operates.
Secure Connection (SSL) specific variables | Description
RANDOM | If using SSL connections, externally generated random data that is stored as a numeric value in the RANDOM variable will be inserted into the initial salt value used to generate temporary key pairs used in SSL hand-shaking. The RANDOM value will only form part of the initial salt value and is an aid to generating more randomness and not an essential requirement.
COBSSL | If using SSL connections specifies the location of the DemoCA directory. If not found, SSLDIR is inspected instead.
SSLDIR | If using SSL connections specifies the generic location of the system's OpenSSL directory.
Parent topic: Environment Variables by Groups


Enterprise Server Communications Environment Variables

Environment variables for configuring the input and output and the display.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: The Environment Variables: Alphabetical Order topic contains the values for most environment variables.
Variable | Description
CCITCP2 | Locates the TCP/IP registration program
CCITCP2_PORT | The port that is being used for the registration process
CCITRACE | Specifies the level of CCI tracing
ES_CAS_API | Indicates whether casout or cassub has been executed by a call and not from the command line
ES_CONSOLE_LOG | Sends console messages to the Windows Event Log
ES_CSKL_NO_MSG_CONSOLE | Stops CSKL writing messages to console.log
ES_ESMAC_DISP_MAX_OVERRIDE | The number of items displayed in the ESMAC catalog view
ES_LEGACY_ECI | Indicates that Enterprise Server must use ES dfhtex32 instead of IBM CTG
ES_MAX_CATALOG_LINES | Restricts the number of entries displayed in ESMAC catalog view
ES_MEM_STRATEGY | Selects the types of memory processes supported
ES_OTMA_TIMEOUT | The time that an OTMA client should wait for an answer
ES_SEP_DORMANT_TIME | Allows override of Transient SEP dormant time
ES_SERVER | Server name (used if no -r switch is specified on casstart or casstop).
ES_SYSOUT_HOLD | Message classes to route to the Out Hold queue
ES_USR_DFLT_ESMAC | Allows you to override the default user when no user is logged on for ESMAC authentication
ES_WS_RUNAWAY_TIMEOUT | Time in seconds that the client will wait for a response from the web service. Only applies when using Net Express to deploy an application.
ISPPROF | The location of ISPF dialog profiles
JAVA_HOME | Locates the JDK
LANG | Specifies the language environment
LINES | Specifies screen depth
LD_LIBRARY_PATH | Locates shared libraries (applies to all operating systems except HP/UX PA-RISC 32 bit and AIX)
LIBPATH | Locates shared libraries (applies to AIX only)
MAINFRAME_FLOATING_POINT | Specifies the format to use for floating point data items
MF_AMODE31ONLY | Indicates that all programs are AMODE(31)
MF_CHARSET | Specifies the system character set (ASCII or EBCDIC)
MF_USESCA5 | Specifies that the server should use version 5 of the Open Service Component Architecture
MF_SPOOL_ARCHIVE_LOC | The location of the file where the contents of the MVS SPOOL spool file are copied prior to deletion
MF_USESCA7 | Specifies that the server should use version 7 of the Open Service Component Architecture
MFCODESET | Specifies which translation tables to use. See Environment Variables: Alphabetical Order for more details.
MFCSCFG | A configuration file to be used by the client/server binding client program
MFEXTMAP | Location of a mapper file
MFLOGDIR | Log file directory
MFLECONFIG | A configuration file for Language Environment (LE) run-time options
MFPRELOAD_USE | Calls MFPRELOAD to improve perfomance
MFSUB | Specifies whether to use SUBI or ASUBI
MFSYSCATDIR | The location of the system catalog directory
MFUSER | Default user ID
MFUSERCAT_LOC | The fully-qualified name of the SMS dataset
MULTMFENTMAP | Specifies whether special characters such as < and & are replaced with the equivalent HTML entities (for example &lt; and &amp;)
OOSW | OO run-time switches
PATH | Locates directories for all UNIX programs
SHLIB_PATH | Locates shared libraries (applies to HP/UX only)
TERM | Specifies terminal type
TERMINFO | Locates the UNIX system terminfo database
TMPDIR | Locates the directory for temporary files
USER | Default user name
Parent topic: Environment Variables by Groups


File Handling and Dataset Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic lists environment variables that relate to configuring the file and dataset handling.

Note: The Environment Variables: Alphabetical Order topic contains the values for most environment variables.
Variable | Description
COBDATA | Specifies the directory or directories that the run-time system is to search for data files. Provides you with the facility to map data files globally, thus enabling you to put working data files in a directory whose name is not known until run time.
COBEXTFHBUF | Specifies that fixed-length sequential files are buffered.
DB2DBDFT | The default database for the DB2 SQL precompiler to process SQL statements against
ES_RLS_FILE_SUPPORT | Stops dirty records being returned when a record is locked by another process.
EXTFH | Specifies a configuration file for the Callable File Handler
FHREDIR | A configuration file to be used by the Fileshare Client
FS | A configuration file to be used by the Fileshare Server
FSCOMMS | Specifies that the Fileshare system is to run in single user mode
HCOBND | A directory for DB2 bind files
LIB | The location of the DB2 LIB directory
MFLOCKING | Enables Locking Support
TXFILEP | The location of Micro Focus VSAM files
Parent topic: Environment Variables by Groups


Input, output and display environment variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

These environment variables relate to configuring the input and output and the display.

Note: The Environment Variables: Alphabetical Order topic contains the values for most environment variables.
Variable | Description
CCITCP2 | Locates the TCP/IP registration program
CCITCP2_PORT | The port that is being used for the registration process
CCITRACE | Specifies the level of CCI tracing
COBAIF | Locates .aif files
COBAIFNAME | The basename of .aif files
COBATTR | Specifies non-standard behavior for HIGHLIGHT and LOWLIGHT clauses used with ACCEPT and DISPLAY statements. It provides compatibility with earlier COBOL products.
COBCONFIG | Specifies a run-time configuration file that tailors the run-time configurable options in some way.
COBCONFIGJVM | Specifies a Java properties file that tailors the run-time configurable options for Java Virtual Machine applications.
COBCONFIG.BLOCK | The location of the application configuration file
COBDIR | Specifies the directory where the required Micro Focus COBOL system is installed. Many of the COBOL system components and utilities require and use this information. If the COBDIR environment variable is not set then the COBOL system acts as if it had been set to the default COBOL system directory.
COBKEYTIMEOUT | Maximum elapsed time, in tenths of a second, for the connected terminal to transmit any valid escape sequence to the run-time system.
COBLANG | The language environment in which your COBOL program runs
COBLPFORM | Logical printer channels
COBMAINSTACK | The size of the main stack
COBMODE | Whether to start the server in 32-bit or 64-bit mode
COBOPT | User default Cob utility options
COBPATH | The location of programs for dynamic loading
COBPRINTER | Specifies the name of a print spooler that is to receive, via its standard input stream (stdin), output from any DISPLAY UPON PRINTER statement.
COBPRFDIR | Location of .ipf files created by programs compiled with the PROFILE compiler directive
COBSES | The UNIX Session Recorder functions to perform
COBSW | Run-time system switch settings for the run-time system to observe when running an application
COBTERMINFO | The directory or directories to be searched by the run-time system for a terminfo database of terminal information tailored to the needs of COBOL applications. This enables COBOL applications to use different terminfo settings to those used by non-COBOL applications, such as vi, when using the same terminal.
COLUMNS | Specifies screen width
ES_CAS_API | Indicates whether casout or cassub has been executed by a call and not from the command line
ES_CONSOLE_LOG | Sends console messages to the Windows Event Log
ES_ESMAC_DISP_MAX_OVERRIDE | The number of items displayed in the ESMAC catalog view
ES_MAX_CATALOG_LINES | Restricts the number of entries displayed in ESMAC catalog view
ES_MEM_STRATEGY | Selects the types of memory processes supported
ES_OTMA_TIMEOUT | The time that an OTMA client should wait for an answer
ES_SEP_DORMANT_TIME | Allows override of Transient SEP dormant time
ES_SERVER | Server name (used if no -r switch is specified on casstart or casstop).
ES_SYSOUT_HOLD | Message classes to route to the Out Hold queue
ES_USR_DFLT_ESMAC | Allows you to override the default user when no user is logged on for ESMAC authentication
ISPPROF | The location of ISPF dialog profiles
JAVA_HOME | Locates the JDK
LANG | Specifies the language environment
LINES | Specifies screen depth
LD_LIBRARY_PATH | Locates shared libraries (applies to all operating systems except HP/UX PA-RISC 32 bit and AIX)
LIBPATH | Locates shared libraries (applies to AIX only)
MAINFRAME_FLOATING_POINT | Specifies the format to use for floating point data items
MF_AMODE31ONLY | Indicates that all programs are AMODE(31)
MF_CHARSET | Specifies the system character set (ASCII or EBCDIC)
MF_USESCA5 | Specifies that the server should use version 5 of the Open Service Component Architecture
MF_USESCA7 | Specifies that the server should use version 7 of the Open Service Component Architecture
MFCODESET | Specifies which translation tables to use. See Environment Variables Alphabetical Order for more details.
MFCSCFG | A configuration file to be used by the client/server binding client program
MFEXTMAP | Location of a mapper file
MFLOGDIR | Log file directory
MFLECONFIG | A configuration file for Language Environment (LE) run-time options
MFPRELOAD_USE | Calls MFPRELOAD to improve perfomance
MFSUB | Specifies whether to use SUBI or ASUBI
MFSYSCATDIR | The location of the system catalog directory
MFUSER | Default user ID
MULTMFENTMAP | Specifies whether special characters such as < and & are replaced with the equivalent HTML entities (for example &lt; and &amp;)
OOSW | OO run-time switches
PATH | Directories to be searched for all UNIX programs
SHLIB_PATH | Locates shared libraries (applies to HP/UX only)
TERM | Specifies terminal type
TERMINFO | Locates the UNIX system terminfo database
TMPDIR | Locates the directory for temporary files
USER | Default user name
Parent topic: Environment Variables by Groups


Security and Auditing Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

These environment variables relate to configuring the security and auditing environment.

Note: The Environment Variables: Alphabetical Order topic contains the values for most environment variables.
Variable | Description
MF_ROOT_CERT | Enables the MF Directory Server process and any client applications to pick up the value of the root certificate file
MFAUDIT_LOGS | The location of audit log files that the auditing sytem generates
Parent topic: Environment Variables by Groups


SORT Engine Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic lists environment variables that relate to the sorting functionality.

Note: The Environment Variables: Alphabetical Order topic contains the values for most environment variables.
Variable | Description
MFJSENGINE | Specifies which sort engine the utility MFJSORT is to emulate.
MFJSTATS | Specifies to create a report containing statistics for a SORT.
SORTCOMPRESS | Tells the system whether or not to execute a compression routine on each record to be sorted. SORTCOMPRESS=5 allows for run-length encoding of sort records, resulting in much better performance when records contain multiple repeated characters. Note that 5 is the only valid value for this environment variable.
SORTSCHEME | Use in conjunction with SORTSPACE for improved performance. This is activated by setting SORTSCHEME=1. This is the only valid value for the environment variable. See SORTSPACE below for more information.
SORTSPACE | The amount of memory to be allocated to internal workspace for SORT operations. This can be specified in different formats: for example, you could specify 64M, 2G, and 1000000 to give sort memory areas of 64 Megabytes, 2 Gigabytes and 1000000 bytes respectively.
SORTTEMPSPACE | The amount of temporary memory to be allocated to internal workspace for SORT operations. This can be specified in different formats much like the SORTSPACE environment variable. By using SORTTEMPSPACE, you can maximize available memory.
SORTTYPE | Setting SORTTYPE=2 forces SORT to use the file handler, so that format modifications are picked up from the extfh.cfg file. Not setting this means SORT will try to use CBL_ routines to read and write files to improve performance. Note that 2 is the only valid value for this environment variable.
Parent topic: Environment Variables by Groups


Tracing and Debugging Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic lists environment variables relate to the tracing and debugging functionality.

Note: The Environment Variables: Alphabetical Order topic contains the values for most environment variables.
Variable | Description
CCITRACE | Specifies the level of CCI tracing
COBANIMOPT | Directives to be used by the debugger
COBANIMSRV | Attaches the debugger to a running program
COBIDY | The location of debugger information (.idy) file for the program being debugged if it is not found in the same directory as the intermediate code (.int) file.
ES_DDBG_PORT_RANGE | A range of ports to use for dynamic debugging
MFTRACE_ANNOTATIONS | The location of the Visual COBOL trace files
MFTRACE_CONFIG | The location of the CTF configuration file
MFTRACE_LOGS | The location of the CTF log files
MFTSO_DEBUG | Controls the display of debug message
Parent topic: Environment Variables by Groups


Reserved Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:
These variables are for Micro Focus use only and must not be set unless advised to do so by Micro Focus Support Line.
APPCLLU | ASLMFNET | BTRMAXREC
BTRPAGE | CCITCPS_servername | CCITCPT_servername
CHECKER | COBFSTATCONV | COBHNF
COMMIT_COUNT | CPDIR | DEBUGEXIT
DSQUERY | DYNDIR | ES_CESN_NO_OS388
ES_DB_APPLICATION_PLAN | ES_DB_PACKAGE_PATH | ES_DB_PACKAGESET
ES_EMP_EXIT_1(n) | ES_MNM_SUPPORT |
ES_IMS_TRACE | ES_HOME | ES_IDEBIN
ES_LOAD_SWITCH_PLUS | ES_LOG_PERF_EVENTS | ES_STAGING_FOLDER
ES_TSC_TRACE | ES_USR_DFLT_JCL | ES_WORKING_MODE
ES_XDBLIB | FSIDXINTEGRITY | FSSERVER
GCC_LIB | HELPFILES | IBM_DBG_IOCRESFILE
IBM_DBG_LANG | IPF_PATH30 |
MF_JOBDIAG | MF_MVSJOB | MF_ROOT_CERT
MF_SPPOOL_HK_TESTDATE | MFAUTOCTL_XREF_DSN | MFDS_PORT
MFE.AMODE31ONLY | MFEDATA | MFE-TRAP-IMS-AMP
MFIMS_DB_AUTOSTOP | MFJCLHF | MFJCOMPARE.FILE
MFJDEBUG | MFJSENGINE | MFJSTATS
MFJUXITLOG | MFMVSUSER | MFREXX_LSEQ_RECSIZE_MAX
MFREXX_NOT | MFREXX_OR | MFUCC12
NCG | NLS_TIMESTAMP_FORMAT |
 | SSLDIR | TMF
TX_UNICLI_SESSIONS | XFH2BTR | XFH2BTR
XFHNODE | LIBLIST |
Parent topic: Environment Variables by Groups


Environment variables in alphabetical order

Restriction: This topic applies only when the Enterprise Server feature is enabled.

C

CCITIMEOUT

Allows the specification, in tenths of seconds, of the maximum time out period that will be used with any LSC style application, such as Drag and Drop, SourceConnect, or the Monitor. The default is 2 minutes (1200), and the maximum value that can be used is 2,147,483,647.

Example for setting this value to 4 minutes:
SET CCITIMEOUT=2400
CCIERRLOG
Specifies the output location and filename of ccierr.log content which tracks first-instance errors reported from the operating systems. CCIERRLOG overrides any entries found in CCI.INI, where the syntax and content is explained in detail.
CCITCP2
Locates the TCP/IP registration program.
Values
  • The name or the IP address of the machine hosting the CCITCP2 registration program.
CCITCP2_PORT
The port that is being used for the registration process.
Values
  • The port on which the CCITCP2 registration program operates.
CCITRACE
Specifies the level of CCI tracing
Values

Filename for and trace output and the trace options. The trace options are as follows:

  • /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.

COBAIF
The path location of the .aif files.
Values
  • The path where the .aif files are located.
COBAIFNAME
The basename of animator session (.aif) files.
Values
  • The base animator session filename.
COBANIMOPT
Additional directives to be used by Animator.
Values
  • An Animator directive, or a list of directives. Must not be a filename.
COBANIMSRV
Attaches Animator to a running COBOL program.
Values
  • The progid identifier that is used to identify the program to which Animator will attach.
COBATTR

Specifies non-standard behavior for HIGHLIGHT and LOWLIGHT clauses used with ACCEPT and DISPLAY statements. It provides compatibility with earlier COBOL products. You should avoid using it wherever possible as support might be discontinued at some future date.

Values

A value in the range 0 through 7. It can be one of the following values, or a cumulative value; for example, specifying a value of 6 would result in the behavior described for values 4 and 2.

  • 0

    Provides standard, default behavior.

    When a COBOL program displays text subject to a HIGHLIGHT or LOWLIGHT clause, the run-time system uses respectively the bold or dim mode specified in the terminfo entry for the terminal. If the bold or dim mode is not specified, then the HIGHLIGHT or LOWLIGHT clause respectively has no effect.

  • 1

    When a COBOL program displays text subject to a HIGHLIGHT clause, the run-time system uses the bold mode. The run-time system uses the default mode for normal text. Specifying dim mode in the terminfo entry for the terminal has no affect. The LOWLIGHT clause has no effect.

  • 2

    High and low intensity space characters are not assumed to be the same as normal mode space characters.

  • 3

    As for 1 and 2 above

  • 4

    Provides compatibility with default behavior of products before COBOL version 3.2.

    When a COBOL program displays text subject to a HIGHLIGHT clause, the effect depends on whether the dim mode is specified in the terminfo entry for the terminal. If dim mode is specified, then the run-time system uses the default mode for highlighted text and the dim mode for normal text. If the dim mode is not specified, then the run-time system uses the bold mode for highlighted text and default mode for normal text. The LOWLIGHT clause has no effect, giving the same appearance as normal text.

COBCONFIG
Specifies a run-time configuration file that tailors the run-time configurable options in some way.
Values
  • The location of a COBOL runtime configuration file.
COBCONFIGJVM
Specifies a Java properties file that tailors the run-time configurable options for Java Virtual Machine applications.
Values
  • The location of a properties file.
COBCONFIG.BLOCK
The location of the application configuration file.
COBDATA
Specifies the directory or directories that the run-time system is to search for data files. Provides you with the facility to map data files globally, thus enabling you to put working data files in a directory whose name is not known until run time..
Values
  • A list of search directories, each item separated by a semicolon.
COBDIR
Specifies the directory where the required Micro Focus COBOL system is installed. Many of the COBOL system components and utilities require and use this information. If the COBDIR environment variable is not set then the COBOL system acts as if it had been set to the default COBOL system directory.
Values
  • A list of search directories, each item separated by a semicolon.
COBEXTFHBUF
Specifies that fixed-length sequential files are buffered.
Values
  • The buffer size in bytes.
COBIDY
The location of Animator information (.idy) file for the program being animated if it is not found in the same directory as the intermediate code (.int) file.
Values
  • A list of search directories, each item separated by a semicolon.
COBKEYTIMEOUT

Specifies the maximum elapsed time, in tenths of a second, for the connected terminal to transmit any valid escape sequence to the run-time system.

Values
  • Terminal timeout time in tenths of a second.
COBLANG
The language environment in which your COBOL program runs
Values
  • A COBOL language environment (LE) value.
COBLPFORM
Logical printer channels.
Values
  • A valid logical printer channel.
COBMAINSTACK
The size of the main stack.
Values
  • A number in the range 1 through nnn that represents the size of the main stack in bytes.
COBMODE
Whether to start the server in 32-bit or 64-bit mode.
Values
  • 32

    The system starts in 32-bit mode

  • 64

    The system starts in 64-bit mode

COBOPT
User default Cob utility options.
Values
  • environment-variable Any one of the environment variables supported by the COBOL system and listed in this appendix.
  • value The value to which you want to set the specified environment variable.
  • options One or more cob command line options. See the chapter COBOL System Interface (cob) for details on the format of cob options.
  • .ext A filename extension that, in addition to the standard ones of .cob, .CBL, or .cbl, denotes a file that Cob should treat as a COBOL source file. The extension must begin with a period, and if more than one is specified on one line then they must be separated by a space or tab character. You can use more than one cobextn line.
  • pathname The directory that the COBOL system is to search for an options file.
  • filename The name of a file containing cob options.
COBPATH
The path location of programs for dynamic loading.
Values
  • A list of search directories, each item separated by a semicolon.
COBPRINTER

Specifies the name of a print spooler that is to receive, via its standard input stream (stdin), output from any DISPLAY UPON PRINTER statement.

Values
  • A command line supported by your system and that can be executed by the system shell. Typically, it is simply the name of a print spooler or other executable, but if the shell is escaped when setting the value then any command-line arguments can be used.
COBPRFDIR
Location of .ipf files created by programs compiled with the PROFILE compiler directive.
Values
  • A list of search directories, each item separated by a semicolon.
COBSES
The UNIX Session Recorder functions to perform.
Values

COBSES={option[filename]}..., where option can be one or more of the following:

  • -a Include keystrokes made to and screen output from the Animator
  • -f filename Play back recording in fast forward mode
  • -p filename Play back recording in filename at normal speed
  • -r filename Record keystrokes
  • -s filename Record screen output
  • -t terminal number Indicate terminal number for multi-user screen recordings
COBSSL
If using SSL connections specifies the location of the DemoCA directory. If not found, SSLDIR is inspected instead.
COBSW
Run-time system switch settings for the run-time system to observe when running an application.
Values

A list of the runtime switches to set or unset.

  • + sets a switch.
  • - un-sets a switch.
COBTERMINFO
The directory or directories to be searched by the run-time system for a terminfo database of terminal information tailored to the needs of COBOL applications. This enables COBOL applications to use different terminfo settings to those used by non-COBOL applications, such as vi, when using the same terminal.
Values
  • A list of search directories, each item separated by a semicolon.
COLUMNS
Sets the screen width.
Values
  • An integer number of columns.

D

DB2DBDFT
The default database for the DB2 SQL precompiler to process SQL statements against.
Values
  • The location and name of the default database.

E

ES_ALLOC_OVERRIDE
The location of a file containing rules that determine where new datasets are created. This applies only to JES and batch files, and not CICS, IMS, or Web services files.
Values
  • File path and name of the dataset rules file.
ES_CAS_API
Indicates whether casout or cassub has been executed by a call and not from the command line
ES_CERT_REG
Specifies the directory in which the cascertreg user certificate utility should store its registrations.
Values
  • pathname
ES_CESN_NO_OS390
Overrides the default behaviour CESN transaction response for invalid user credentials. Default behaviour reports "Your userid is invalid" or "Your password is invalid".
Values
  • Setting this variable to any value causes CESN to produce an invalid credential message instead of a specific invalid user or invalid password message.
ES_CONSOLE_LOG
Sends console messages to the Windows Event Log
Values
  • Yes Console messages are sent to the Windows Event Log
ES_DDBG_PORT_RANGE
A range of ports to use for dynamic debugging
ES_ESMAC_DISP_MAX_OVERRIDE
The number of items displayed in the ESMAC catalog view
Values
  • An integer number of the ESMAC catalog view items to display.
ES_MAX_CATALOG_LINES
Restricts the number of entries displayed in ESMAC catalog view
ES_MEM_STRATEGY
Selects the types of memory processes supported
ES_MQ_1PC
Indicates whether the MQSeries switch module ESMQXA should operate in one-phase commit mode. Only set this when advised to do so by Micro Focus.
ES_MQ_LIB_XA
The full name including the path of the IBM MQ XA library
Important: In AIX environments the library is an object inside a shared object. For example:
ES_MQ_LIB_XA="/usr/mqm/lib64/libmqmxa64.a(libmqmxa64.o)"
ES_MQ_LIB_XA_T
The full name including the path of the IBM MQ XA library, for threaded environments
ES_MQ_XA
The type of XA structure to use for the two-phase commit XA switch module.
Values
  • D: use a dynamic XA structure
  • S: use a static XA structure
ES_OLD_SEC_TSTD
Prevents security being enforced for TS or TD queues that are not declared in the security repository.
ES_OTMA_TIMEOUT
The time that an OTMA client should wait for an answer
ES_RLS_FILE_SUPPORT
Stops dirty records being returned when a record is locked by another process.
ES_SEP_DORMANT_TIME
Allows override of Transient SEP dormant time
ES_SERVER
Server name (used if no -r switch is specified on casstart or casstop).
ES_SYSOUT_HOLD
Sysout held classes
ES_USR_DFLT_ESMAC
Allows you to override the default user when no user is logged on for ESMAC authentication
ES_XA_????_NB_RETRIES
Operates in conjunction with ES_XA_CONNECT. Sets the number of connection re-tries when attempting to connect to a resource:

ES_XA_????_NB_RETRIES= nnnn where:

  • ???? is the XA ID defined in MFDS.
  • nnnn is the number of subsequent XA call failures allowed before the SEP is recycled and the switch disabled.
ES_XA_LOG_SUPPRESS
Suppresses XA logging and the recovery of in-doubt XA transactions if set to Y.
Values
  • No Value (default)
  • Y
ES_XA_RECONNECT

If this environment variable is set, when an error occurs on a call to XA, the server recycles the SEP and attempts to reconnect to the Resource Manager. The ES_XA_????_NB_RETRIES variable specifies the number of XA call failures allowed before the SEP is recycled and the switch disabled.

EXTFH
Specifies a configuration file for the Callable File Handler

F

FHREDIR
A configuration file to be used by the Fileshare Client.
FS
A configuration file to be used by the Fileshare Server.
FSCOMMS
Specifies that the Fileshare system is to run in single user mode.
Values
  • "\$local" Run the Fileshare System in single user mode.

H

HCOBND
A directory for DB2 bind files.

I

ISPPROF
The location of ISPF dialog profiles.

J

JAVA_HOME
Locates the JDK.

L

LANG
Specifies the language environment.
Values
  • language The language in which your program is to run.
  • _ (underscore) The delimiter for language and territory, if territory is specified.
  • territory The country in which your program is to run.
  • . (period) The delimiter for territory and codepage, if codepage is specified.
  • codepage The character set to use for your program.

Example: LANG=fr_FR

LD_LIBRARY_PATH

Specifies the directory or directories for the UNIX system, Cob and the run-time system to search for shared libraries and callable shared objects. It must be set to include $COBDIR/lib on all platforms, except AIX and HP/UX, which use a different environment variable. It should also include any directories that contain callable shared objects used by your application.

Values
  • A path or a list of paths, each separated by a colon (:).
LIB
The location of the DB2 LIB directory
LIBPATH
Locates shared libraries (applies to AIX only).
Values
  • A path or a list of paths, each separated by a colon (:).
LINES
Specifies screen depth in lines.
Values
  • An integer that specifies the number of lines.

M

MF_ALIAS
Specifies program aliases. Each set (pair) is 16 characters long - 8 characters for the program-name, and 8 characters for the alias. You can specify up to 10 pairs. This list is searched first and thus can potentially override the built-in list. If not found, the built-in alias table is searched.
MF_AMODE31ONLY
Indicates that all programs are AMODE(31).
MF_CHARSET
Specifies the system character set (ASCII or EBCDIC).
MF_DUPJOBS
Enables jobs with identical names to run.
Values:
  • Y (Default)
  • N
MF_ROOT_CERT
Enables the MF Directory Server process and any client applications to pick up the value of the root certificate file
MF_SMS
Enables SMS support
MF_SPOOL_HK_TESTDATE
Spool housekeeping testing date override.
MF_USESCA5
Specifies that the server should use version 5 of the Open Service Component Architecture
Values:
  • ON (Default)
  • OFF
MFAUDIT_LOGS
The location of audit files.
MFCODESET
Specifies which translation tables to use.
Values
  • A pre-defined country code:
    Country code | Language
    DEFAULT | English (US)
    AUTO or AUTOMATIC | Operating system default
    0031 | Dutch
    0033 | French
    0034 | Spanish
    0039 | Italian
    0043 | German (Austrian)
    0044 | English (UK)
    0045 | Danish
    0046 | Swedish
    0047 | Norwegian
    0049 | German
    0081 | Japanese Katakana Extended
    0082 | Korean
    0086 | Simplified Chinese
    0351 | Portuguese
    0358 | Finnish
    0437 | English (US)
    0500 | International (Latin 1)
    0886 | Traditional Chinese
    0939 | Japanese Latin Extended
    9122 | Japanese Katakana

  • A code between 2000 and 9999 (except 9122), which corresponds to a user-defined translation table. User-defined tables are created using the Codecomp utility.

Always prefix the country code for EURO codesets with "E".

MFCSCFG
A configuration file to be used by the client/server binding client program
MFE.SMS
Enables SMS support.
MFEXTMAP
Location of a mapper file.
MFJ_INPUTDS_ERROR
When set to N, this will cause IEBDG, IEBGENER and IEBCOMPR to treat missing files as though they were present but empty.
MFJSENGINE
Specifies which sort engine the utility MFJSORT is to emulate.
Values:
  • DFSORT (Default)
  • SYNCSORT
MFJSTATS
Specifies to create a report containing statistics for a SORT.
MFLECONFIG
Path and filename for a configuration file for Language Environment (LE) run-time options
MFLOCKING
Enables Locking Support
MFLOGDIR
A directory that the client/server binding process is to use for log files.
MFPRELOAD_USE
Calls MFPRELOAD to improve performance.
MFREXX_LSEQ_RECSIZE_MAX

Specifies the record length for the REXX EXECIO command when reading or writing a line sequential file that has been cataloged with a record length of zero.

Values:
  • Record length to use (Default = 255)
MFREXX_NOT
Specifies one or more characters to be used for the NOT operator in addition to REXX's default, which is "¬".
Values
  • One or more characters for each operator; each character you specify is used in addition to the default operator. Each additional character must be defined within single or double quotes, or in hexadecimal. Separate multiple characters with a space or a comma.
MFREXX_OR
One or more characters to be used for the OR operator in addition to REXX's default, which is "|".
Values
  • One or more characters for each operator; each character you specify is used in addition to the default operator. Each additional character must be defined within single or double quotes, or in hexadecimal. Separate multiple characters with a space or a comma.
MFSUB
Specifies whether to use SUBI or ASUBI
Values
  • SUBI
  • ASUBI
MFSYSCATDIR
The location of the system catalog directory
MFTRACE_ANNOTATIONS
The location of the trace files
MFTRACE_CONFIG
The location of the CTF configuration file
MFTRACE_LOGS
The location of the CTF log files
MFTSO_DEBUG
Controls the display of debug message
MFUSERCAT_LOC
User catalog location
MULTMFENTMAP
Specifies whether special characters such as < and & are replaced with the equivalent HTML entities (for example &lt; and &amp;)

O

OOSW
OO run-time switches

P

PATH
Directories to be searched for all UNIX programs.

R

RANDOM
If using SSL connections, externally generated random data that is stored as a numeric value in the RANDOM variable will be inserted into the initial salt value used to generate temporary key pairs used in SSL hand-shaking. The RANDOM value will only form part of the initial salt value and is an aid to generating more randomness and not an essential requirement.

S

SHLIB_PATH
Locates shared libraries (applies to HP/UX only).
SORTCOMPRESS
Tells the system whether or not to execute a compression routine on each record to be sorted.
Values
  • SORTCOMPRESS=5 allows for run-length encoding of sort records, resulting in much better performance when records contain multiple repeated characters.
    Note: 5 is the only valid value for this environment variable.
SORTSCHEME
Activates a sortscheme. Use in conjunction with SORTSPACE for improved performance.
Values
  • SORTSCHEME=1 - this is the only valid value for the environment variable. See SORTSPACE below for more information.
SORTSPACE
The amount of memory to be allocated to internal workspace for SORT operations. This can be specified in different formats: for example, you could specify 64M, 2G, and 1000000 to give sort memory areas of 64 Megabytes, 2 Gigabytes and 1000000 bytes respectively.
Values
  • n[K|k|M|m|G|g No letter indicates bytes. Defaults to 1 megabyte.
SORTTEMPSPACE
The amount of temporary memory to be allocated to internal workspace for SORT operations. This can be specified in different formats much like the SORTSPACE environment variable. By using SORTTEMPSPACE, you can maximize available memory.
SORTTYPE
Defines the sort type.
Values
  • SORTTYPE=2 Forces SORT to use the file handler, so that format modifications are picked up from the extfh.cfg file.
  • Not setting this means SORT will try to use CBL_ routines to read and write files to improve performance.
Note: "2 is the only valid value for this environment variable.
SSLDIR
If using SSL connections specifies the generic location of the system's OpenSSL directory.

T

TERM
Sets the terminal type.
Values
  • name The name of the terminal in the terminfo database.
TERMINFO
Locates the UNIX system terminfo database.
TMPDIR
Locates the directory for temporary files.
TXFILEP
The location of Micro Focus VSAM files.

U

USER
Default user name.
Parent topic: Configuring Environment Variables


Configuring Fileshare

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You will need to set the FHREDIR environment variable to specify the location of the FHREDIR configuration file if any services in your enterprise server instance make use of Fileshare to access files across the network. For example:

[ES-Environment]
FHREDIR=home/mydir/client.cfg

As the FHREDIR configuration is static, the contents of the FHREDIR configuration file are read at when the enterprise server instance is initialized and cannot be dynamically changed. This means that the FHREDIR configuration file should contain entries for all services that are deployed, or could be deployed to the enterprise server instance. If a service is dynamically deployed to an enterprise server instance and it requires different configuration for Fileshare then there is no option but to stop and restart the enterprise server instance.

If all your enterprise server instances use the same configuration file, you can set $FHREDIR on the command line before you start the Directory Server, rather than have separate configuration entries for each enterprise server instance.

You should start all the Fileshare servers that the services in an enterprise server instance might need to access before you start the enterprise server instance. You should stop the enterprise server instance before you stop the Fileshare servers.

For more information about Fileshare see the section of the help that covers Fileshare.

Parent topic: Configuring the Server Instance Environment


Using XA-Compliant Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • XA-Compliant Resources Overview
  • XA Switch Modules
  • Configuring XA Resources for an Enterprise Server Instance
  • XA Troubleshooting
  • Handling XA Connection Errors
  • Recovery of in-doubt XA transactions
Parent topic: Configuring the Server Instance Environment


XA-Compliant Resources Overview

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you configure your enterprise server instance to run container-managed services (Web services or EJBs), you also need to configure your server so that it can interact with the resource managers that the application wants to access. In that context you can only use resource managers that are XA-compliant. The XA interface describes a structure called a switch table, which lists the names of the xa_ routines implemented in the resource manager. This structure is called xa_switch_t. To access an XA-compliant resource manager, you need a switch module, the purpose of which is to obtain the address of the XA switch data structure implemented by the resource manager.

You specify the details of XA resource managers using the Edit Server > Properties > XA Resources page in the Web interface. You can also edit and delete XA resource manager definitions. You can enable resource managers individually to control which are active when an enterprise server instance starts.

Parent topic: Using XA-Compliant Resources


XA Switch Modules

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: Source code for XA switch modules is not installed with COBOL Server.

You can add support for other XA-compliant database managers. To do this, you write and compile a switch module for the database. See the database vendor's documentation for advice on how to do this.

Generic One-phase Commit for ODBC Limitations
When using the Generic one-phase commit for ODBC switch modules, the following SQL operations are not supported in the source for your deployed container-managed service:
  • CONNECT
  • DISCONNECT
  • BEGIN TRANSACTION
  • COMMIT
  • ROLLBACK
ODBC Requirements
Some OpenESQL directives are process-based, and typically need to be set in within the code of the program that makes the database connection. If you are executing services under Enterprise Server that are deployed as container-managed applications these directives must be specified when compiling the XA switch module, rather then when compiling your program source.
ODBC Limitations
The ODBC module supports only a one-phase commit, and hence:
  • Cannot be used in conjunction with other resource managers that use this module because, within a given region, the generic ODBC one-phase commit module supports only one active Resource Manager at a time.
  • Can only be used for a single database connection; multiple data source connections are not supported
Additional Oracle Resources
For more information on using the Oracle XA switch module, including the Open String definition and details of supported SQL operations, see the following:
  • The Database Access Support topic for Third-party Software in the Start Here section of this documentation.
  • The Developing Applications with Oracle XA help topic available in the Oracle RDBMS documentation.
Additional IBM DB2 Resources
For more information on using the IBM DB2 XA switch module, including the Open String definition and details of supported SQL operations, see the following:
  • The Database Access Support topic for Third-party Software in the Start Here section of this documentation.
  • The Transaction Managers help topic available in the IBM RDBMS documentation.
  • DB2 9.1 - The X/Open XA Interface programming considerations help topic available in the IBM RDBMS documentation.

The MQSeries XA Switch

The ESMQXA module is provided as part of the product and does not need to be built. The filename for the built module is esmqxa.dll.

By default, the ESMQXA module operates in two-phase commit mode. You can set the environment variable ES_MQ_1PC to Yes or True in order for the module to operate in one-phase commit mode, but you should only do this if advised to by Micro Focus.

In UNIX environments, to use the MQSeries switch, you must have IBM WebSphere MQSeries Server or IBM WebSphere MQSeries Client installed. If they are not installed at the default location, you must use the ES_MQ_LIB_XA environment variable (or the ES_MQ_LIB_T environment variable for threaded environments) to identify the full name including the path of the IBM MQ XA library appropriate to your platform.
Important: In AIX environments the library is an object inside a shared object. For example:
ES_MQ_LIB_XA="/usr/mqm/lib64/libmqmxa64.a(libmqmxa64.o)"
Important: Set the MQ Connection in one of these two places:
  • XA Resource Manager
  • System Initialization Table (SIT)
Do not set it in both. Doing so results in two connections between the COBOL Server region and the MQ Queue Manager. Only one is required.
Parent topic: Using XA-Compliant Resources


Configuring XA Resources for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Add an XA Resource
  • To Delete an XA Resource
  • To Edit an XA Resource
  • To Enable or Disable an XA Resource
Parent topic: Using XA-Compliant Resources


To Add an XA Resource

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server that you want to edit.
  2. Click the XA Resources tab.
  3. Click Add.
  4. Specify the details of the resource manager:
    ID
    Specify a resource manager ID, used internally to identify a particular XA configuration. This must be unique within the enterprise server. Mandatory.
    Name
    Specify the name by which the resource manager is known. It should match the name returned in the name field of the xa_switch_t structure. Mandatory.
    Module
    Specify the location of the executable file (.dll on Windows, .sl on HP-UX PA-RISC, and .so on other UNIX platforms) that contains the entry point that returns the xa_switch_t structure to the enterprise server. Mandatory.
    Open string
    Specify the string that is passed to the resource manager on the xa_open() call. It usually contains at least the database name, and the user ID and password for connecting to the database. The contents of this string are database-specific.

    Where the resource manager supports dynamic registration, and the database vendor requires the name of the module that provides the ax_reg function, you should specify casaxlib.

    Close string
    The string that is passed to the resource manager on the xa_close() call. To find out whether or not you need to supply Close string, see your database vendor's documentation.
    Description
    Specify an optional text description of the resource manager definition.
    Enabled
    Check this to enable the resource manager. It is checked by default.
  5. Click Add.
Note: You cannot add a resource manager until all the mandatory fields have values.
  • Resource Manager Definition for Generic One-phase Commit for ODBC Switch Module
  • Resource Manager Definition for DB2 Switch Module
  • Resource Manager Definition for Oracle Switch Module
  • Resource Manager Definition for MQSeries
Parent topic: Configuring XA Resources for an Enterprise Server Instance
Parent topic: Work with Servers


Resource Manager Definition for Generic One-phase Commit for ODBC Switch Module

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To define the generic one-phase commit for ODBC XA switch module in COBOL Server, add an XA resource including the following values.

  • In the Module field, enter the full path to ESODBCXA.so (32-bit) or ESODBCXA64.so (64-bit).
  • In the Open string field, type the following:
    DSN=odbc_dsn[,USRPASS=userid.password]
    where the parameters are:
    odbc_dsn
    The ODBC Data Source Name used to connect to the data source as defined within your ODBC driver configuration.
    userid
    The user ID required to connect to the data source. Not required when using trusted connections.
    password
    The password required to connect the user ID to the data source. Not required when using trusted connections.

Alternatively, you can specify the DSN, user ID, and password by manually coding them into the ESODBCXA.CBL source. This can be helpful if you want to ease security. To do this, search for CUSTOMIZE within ESODBCXA.CBL to see where to apply the required changes.

Parent topic: To Add an XA Resource


Resource Manager Definition for DB2 Switch Module

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To define the DB2 switch module in COBOL Server, add an XA resource including the following values in the Open string field.

Note: The open string format is defined by IBM. We strongly recommend that you become familiar all of the available options by reviewing the DB2 Administration Guide and the Application Programmer's Guide in your IBM documentation. Example settings are shown in this topic for guidance only.

Enclose values containing spaces in double quotes.

db=name,uid=identifier,pwd=password,axlib=casaxlib
The parameters are:
db
The name of your DB2 database.
uid
The user ID required to connect to the DB2 server.
pwd
The password required to connect the user ID to the DB2 Server. Required.
axlib
The fully-qualified name of the library that contains the transaction manager's ax_reg and ax_unreg functions. Must be set to casaxlib or casaxlib64 for 64-bit applications.
Parent topic: To Add an XA Resource


Resource Manager Definition for Oracle Switch Module

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To define the Oracle switch module in COBOL Server, add an XA resource including the following values in the Open string field.

Important: The open string format is defined by Oracle. We strongly recommend that you become familiar all of the available options by reviewing the Oracle Application Developer's Guide - Fundamentals topic in your Oracle documentation. Example settings are shown in this topic for guidance only.

Enclose values containing spaces in double quotes.

LogDir=path+DbgFl=value+Oracle_XA+SesTm=time+SqlNet=name+Acc=P/user/password
The parameters are:
LogDir
Fully-qualified path to the directory where the XA library error and tracing information may be logged.
DbgFl
Extent of tracing. Possible values are
  • 0x1, trace the entry and exit to each procedure in the XA interface
  • 0x2, trace the entry to and exit from other non-public XA library routines
  • 0x4, trace various other calls made by the XA library, such as specific calls to the Oracle Call Interface
Oracle_XA
The name of the resource manager.
SesTm
The maximum length of time a transaction can be inactive before it is automatically aborted by the system.
SqlNet
A string providing the Net8 database link used to log on to the Oracle system.
Acc
User access credentials, which must be prefixed by "P/".
Parent topic: To Add an XA Resource


Resource Manager Definition for MQSeries

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To define the MQSeries XA switch module in Enterprise Server, add an XA resource including the following values.

  • In the Module field, enter the full path to esmqxa.extension.
  • n the Open string field, type the following:
    QMNAME=queue_manager_name,TPM=CICS,AXLIB=casaxlib,CHANNEL,TRPTYPE,CONNAME
    where the parameters are:
    QMNAME
    The name of the queue manager. This is a mandatory parameter.
    TPM
    The transaction manager being used. Must be set to CICS.
    AXLIB
    The name of the library that contains the transaction manager's ax_reg and ax_unreg functions. Must be set to casaxlib.
    CHANNEL
    The name of an MQI channel. If this parameter is supplied, the CONNAME parameter must also be supplied.
    TRPTYPE
    The communications protocol for the MQI channel. The following are valid values:
    LU62
    SNA LU 6.2
    NETBIOS
    NetBIOS
    SPX
    IPX/SPX
    TCP
    TCP/IP
    The default is TCP.
    CONNAME
    The network address of the queue manager. The valid values of this parameter depend on the value of the TRPTYPE parameter.
    If TRPTYPE is set to: CONNAME must be:
    LU62 A symbolic destination name, which identifies a CPI-C side information entry.

    You cannot use the network qualified name of a partner LU or a partner LU alias.

    NETBIOS | A NetBIOS name.
    SPX A 4-byte network address, a 6-byte node address, and an optional 2-byte socket number.

    These values must be specified in hexadecimal notation. A period must separate the network and node addresses, and any socket number must be enclosed in parentheses. For example:

    0a0b0c0d.804abcde23a1(5e86)

    The default value is 5e86.

    TCP | A host name or an IP address, optionally followed by a port number in parentheses. The default value is 1414.
    If this parameter is supplied, the CHANNEL parameter must also be supplied.
Parent topic: To Add an XA Resource


To Delete an XA Resource

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:
Deleting a registered XA resource might cause application connection errors and loss of data.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server that owns the XA resource you want to delete.
  2. Click the XA Resources tab.
  3. Click Edit next to the XA resource you want to delete.
  4. Click Delete.
  5. Click OK on the confirmation page.
Note:

You cannot delete an XA resource if the server is started.

Parent topic: Configuring XA Resources for an Enterprise Server Instance
Parent topic: Work with Servers


To Edit an XA Resource

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server that owns the XA resource you want to edit.
  2. Click the XA Resources tab.
  3. Click Edit next to the XA resource you want to edit.
  4. Update the attributes on the page as required.
  5. Click OK.
Note: You cannot update the attributes of an XA resource if the server is started.

To reconnect to an XA resource following an error

Set the ES_xxxxx_NB_RETRIES environment variables in Configuration Information on the Edit Server page, where xxxxx is the ID of the resource. This specifies the number of times a SEP will attempt to reconnect to the XA resource following an error. The default is 5. If no connection is made, the switch is disabled.

Parent topic: Configuring XA Resources for an Enterprise Server Instance
Parent topic: Work with Servers


To Enable or Disable an XA Resource

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server that owns the XA resource you want to enable or disable.
  2. Click the XA Resources tab.
  3. Click Edit next to the XA resource you want to enable or disable.
  4. Check or uncheck Enabled as required.
  5. Click OK on the confirmation page.
Parent topic: Configuring XA Resources for an Enterprise Server Instance
Parent topic: Work with Servers


XA Troubleshooting

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • XA Troubleshooting
  • XA Return Codes
  • XA Switch Module Diagnostics
Parent topic: Using XA-Compliant Resources


XA Troubleshooting

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Reading Error Messages in console.log

On an XA call failure a message is displayed in the log containing :

  • the target resource manager
  • the failing XA call
  • the return code from the call
  • the XID, a transaction identifier
For example, the log entry
111012 14063540   1924 XATEST   CASXO0004S Resource Manager for resource DB7R Transaction end failed: reason -00007, XID: MF_CASDEMOXATEST  000012000000000000000001000001  14:06:35
The XA End call for resources DB7R failed with return code -00007
includes the following information:
  • CASXO0004S is the error code
  • DB7R is the resource manager
  • Transaction end is the stage of the transaction where the failure occured
  • -00007 is a code indicating the resource manager is unavailable
  • MF_CASDEMOXATEST 000026000000000000000001000001 is the XID

Refer to the specific database documentation for recommendations on the action to take when transactions might have failed.

Understanding Enterprise Server XIDs

The XID transaction identifier consists of the following parts:

Element | Length | Description
fxid-id | 6 char | Constant
xid-sysid | 4 char | System identifier (SYSID of your enterprise server)
xid-applid | 8 char | Region name (APPLID)
xid-mgr-id | 18 numeric | Position of this resource manager in the resource manager table
xid-branch-no | 6 numeric | Branch number

Reading CAS Traces

If you have enabled resource manager interface or exit traces, or if an XA call fails (in which case traces are unconditionally written) you can trace XA calls. Some examples follow.

Example 1
This trace shows a sucessful start call for a resource called NJFXA1.
Succesful START call
uExit(NJFXA1..) 288 61 11100 40 e90181 9171356 <NJFX A1..> 4e4a4658 41310000 SEP dfheserv(dfhcpuex)
XA(start) 290 61 11100 6d 6d0183 9171356 <XA-- STRT> 58412d2d 53545254 SEP dfhexa()
XA-ID(NJFXA1..) 291 61 11100 6d 6d0282 9171356 <NJFX A1..> 4e4a4658 41310000 SEP dfhexa()
XA-StartT( 61 )Br( 1 ) 292 61 11100 6d 6da081 9171356 <...= ....> 0000003d 00000001 SEP dfhexa()
XA-Start( 0 ) 293 61 11100 6d 6d1182 9171356 <XSTR ....> 58535452 00000000 SEP dfhexa()
XA-Return( 0 ) 294 61 11100 6d 6d0384 9171356 <XARC ....> 58415243 00000000 SEP dfhexa()
Example 2
This trace shows a failing start call for NJFXA1, which returns code 4 "Found the previous Start call for this Failing Commit call". The trace includes the XA transaction ID and the resource manager ID.
uExit(NJFXA1..) 120 57 11100 40 e90181 9165273 <NJFX A1..> 4e4a4658 41310000 SEP dfheserv(dfhcpuex)
XA(T-Sync) 122 57 11100 6d 6d0183 9165273 <XA-T SYNC> 58412d54 53594e43 SEP dfhexa()
XA-ID(NJFXA1..) 123 57 11100 6d 6d0282 9165273 <NJFX A1..> 4e4a4658 41310000 SEP dfhexa()
XA-CommitRC( 4 ) 124 57 11100 6d 6d5082 9165273 <XCOM ....> 58434f4d 00000004 SEP dfhexa()
XA-CommitRC( 4 ) 125 57 11100 6d 6d52f9 9165273 <COMM ....> 434f4d4d 00000004 SEP dfhexa()
XA-Return( 1 ) 130 57 11100 6d 6d0384 9165313 <XARC ....> 58415243 00000001 SEP dfhexa()
XA-StartT( 61 )Br( 1 ) 292 61 11100 6d 6da081 9171356 <...= ....> 0000003d 00000001 SEP dfhexa()

The XID for the failing transaction is MF_CASDEMOCICS-FS 00006 0000000000000000001000001.

Parent topic: XA Troubleshooting


XA Return Codes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

As with flag definitions, all transaction managers and resource managers must ensure interchangeability by using these return codes, defined in the xa.h header.

ax_() return codes (transaction manager reports to resource manager)

#define | Code | Description
TM_JOIN | 2 | Caller is joining existing transaction branch
TM_RESUME | 1 | Caller is resuming association with suspended transaction branch
TM_OK | 0 | Normal execution
TMER_TMERR | -1 | An error occurred in the transaction manager
TMER_INVAL | -2 | Invalid arguments were given
TMER_PROTO | -3 | Routine invoked in an improper context

xa_() return codes (resource manager reports to transaction manager)

#define | Code | Description
XA_RBBASE | 100 | The inclusive lower bound of the rollback codes
XA_RBROLLBACK | XA_RBBASE | The rollback was caused by an unspecified reason
XA_RBCOMMFAIL | XA_RBBASE+1 | The rollback was caused by a communication failure
XA_RBDEADLOCK | XA_RBBASE+2 | A deadlock was detected
XA_RBINTEGRITY | XA_RBBASE+3 | A condition that violates the integrity of the resources was detected
XA_RBOTHER | XA_RBBASE+4 | Tthe resource manager rolled back the transaction branch for a reason not on this list
XA_RBPROTO | XA_RBBASE+5 | A protocol error occurred in the resource manager
XA_RBTIMEOUT | XA_RBBASE+6 | A transaction branch took too long
XA_RBTRANSIENT | XA_RBBASE+7 | May retry the transaction branch
XA_RBEND | XA_RBTRANSIENT | The inclusive upper bound of the rollback codes
XA_NOMIGRATE | 9 | Resumption must occur where suspension occurred
XA_HEURHAZ | 8 | The transaction branch may have been heuristically completed
XA_HEURCOM | 7 | The transaction branch has been heuristically committed
XA_HEURRB | 6 | The transaction branch has been heuristically rolled back
XA_HEURMIX | 5 | The transaction branch has been heuristically committed and rolled back
XA_RETRY | 4 | Routine returned with no effect and may be reissued
XA_RDONLY | 3 | The transaction branch was read-only and has been committed
XA_OK | 0 | Normal execution
XAER_ASYNC | -2 | Asynchronous operation already outstanding
XAER_RMERR | -3 | A resource manager error occurred in the transaction branch
XAER_NOTA | -4 | The XID is not valid
XAER_INVAL | -5 | Invalid arguments were given
XAER_PROTO | -6 | Routine invoked in an improper context
XAER_RMFAIL | -7 | Resource manager unavailable
XAER_DUPID | -8 | The XID already exists
XAER_OUTSIDE | -9 | Resource manager doing work outside
Parent topic: XA Troubleshooting


XA Switch Module Diagnostics

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The SQL Server and ODBC switch modules have been coded to use the Consolidated Trace Facility to aid in debugging any errors returned during operation. We have provided a configuration file, ctf.cfg, by default located in the $COBDIR/src/enterpriseserver/xa directory, to serve as a starting point. To enable this facility:

  1. Edit the ctf.cfg file using any text editor and change the location parameter on line 6 to the directory where you want to store your trace files.
  2. Create a new system environment variable named MFTRACE_CONFIG, and set its value to the full path where ctf.cfg is located.
  3. Reboot your system to register MFTRACE_CONFIG.
  4. Start Enterprise Server.

Once enabled, the Consolidated Trace Facility writes SQLCODE, SQLSTATE and any associated SQL error messages to a trace file named cassi.textfile.processid.log, located in the directory you specified. Processid is the process ID under which the Enterprise Server SEP was running when the logfile was created.

Parent topic: XA Troubleshooting
Related information
Components Traced by CTF


Handling XA Connection Errors

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The way a server instance handles XA resource connection errors is controlled by the following environment variables:

ES_XA_RECONNECT
If this environment variable is set to True, when an error occurs on a call to XA, the server attempts to reconnect to the Resource Manager.

If it cannot reconnect, the server monitors the number of attempts made.

ES_XA_????_NB_RETRIES
The format for setting this is:
ES_XA_????_NB_RETRIES=nnnn

where ???? defines the XA ID, and nnnn is the number of subsequent XA call failures allowed before the SEP is recycled and the switch disabled. The default is 5 and its maximum value is 254. If you set nnnn to -1 or a number greater than 254, your switch module will never be disabled and reconnection attempts will continue indefinitely.

Note:

At startup time steps are started switch module loaded and xa_open executed. If xa_open fails the switch is immedialy disabled

If this initial xa_open call is successful:
  • Each time an XA transaction is executed, if a call on an XA verb fails, the retries counter is increased by 1.
  • When the maximum number of retries is reached, the SEP is marked "dirty" and recycled.
  • If the initial xa_open call in the replacing SEP still fails, the switch is disabled and you must use ESMAC to reenable the switch after the issue with the database is fixed.

If the maximum number of call failures is reached, disabling your switch module, and ES_XA_RECONNECT is set to True, you can reenable the switch by starting Enterprise Server Monitoring and Control (ESMAC) and performing the following steps:

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To reenable the switch module:

  1. In the Resources options, select Active.
  2. Select XAT.
  3. Click on the relevant disabled resource from the list of active ones to open the details for that XAT.
  4. Check the Enable box.
Parent topic: Using XA-Compliant Resources


Recovery of in-doubt XA transactions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Some events (e.g. the accidental killing of a SEP) can result in 'in-doubt' transactions - where all parts of a composite transaction are not committed through all participating resource managers.

When resource managers are left with such in-doubt transactions, they are recovered by an internal transaction and reported to the console log:
CASXO0027I XA recovery committed in-doubt transaction 177969 branch 1 on RM ESMQXA4 16:17:38
CASXO0027I XA recovery committed in-doubt transaction 177969 branch 1 on RM XADB2 16:17:38
During start-up after such a failure, Enterprise Server reports any potential in-doubt transactions to the console log:
CASXO0029I XA log reported in-doubt transaction 177969 branch 1 16:30:33
CASXO0029I XA log reported in-doubt transaction 249152 branch 3 16:30:33
Later during the start-up process, the resource managers are recovered and this work is reported to the console log:
CASXO0027I XA recovery committed in-doubt transaction 249152 branch 3 on RM ESMQXA4 16:30:41
CASXO0027I XA recovery committed in-doubt transaction 249152 branch 3 on RM XADB2 16:30:41

Note that during the restart, the resource managers were not aware of transaction 177969 branch 1 above because it was recovered by the internal XA recovery transaction before the crash.

The previous examples illustrated cases when the transactions were ultimately committed, but situations requiring rollback are also handled and reported:
CASXO0028I XA recovery rolled back in-doubt transaction 182303 branch 1 on RM ESMQXA4 16:18:10
CASXO0028I XA recovery rolled back in-doubt transaction 182303 branch 1 on RM XADB2 16:18:10

XA logging

XA logging is the mechanism underpinning the recovery of in-doubt transactions. XA logging is bypassed completely if:
  • There are no xa_recover() capable RM switch modules configured.
or
  • Switch modules report XA_RDONLY during xa_prepare().
or
  • The RM has not dynamically registered for the current transaction.

Configuring the recovery of in-doubt XA transactions

By default, XA logging is enabled for qualifying resource managers. Depending upon your environment, this support may impact performance, and it can be disabled by adding the following environment variable to the Enterprise Server General Configuration area below the [ES-Environment] tag:
ES_XA_LOG_SUPPRESS=Y
Parent topic: Using XA-Compliant Resources


Configuring and Administering Enterprise Server Instances

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Enterprise Server user interface displays a list of the enterprise server instances that your installation maintains. The interface displays whether each enterprise server instance is running or stopped, and also some details for each server.

You can view and configure the details for each enterprise server instance, and for the ones that are running, you can access the Enterprise Server Monitor and Control (ESMAC) screen, to view and configure operating configurations.

  • Creating and Configuring Enterprise Server Instances
  • Connecting to a Server Instance
  • Administering Enterprise Server Instances using ESMAC
  • Stopping and Restarting an Installation
  • Using the Command-line Interface
Parent topic: Enterprise Server configuration and administration


Creating and Configuring Enterprise Server Instances

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes the processes and methods for creating, licensing, configuring, and deleting Enterprise Server instances.

  • To Add an Enterprise Server Instance
  • To Change the Number of ES licenses
  • To Copy an Enterprise Server Instance
  • To Delete an Enterprise Server Instance
  • To Delete a CCI Server
  • To Export Server Information
Parent topic: Configuring and Administering Enterprise Server Instances


To Add an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Home page of Enterprise Server Administration, click Add at the bottom of the table of servers.
  2. Specify a name for the server in Name.
  3. Select the Working Mode for the server. If you are creating your server in an environment that supports both 32-bit and 64-bit applications, you must specify the server's working mode. A server with a 32-bit working mode can run only 32-bit applications. A server with a 64-bit working mode can run only 64-bit applications.
    Note:
    • You cannot change the working mode of the server once it has been created. You can however, change the mode when you copy or import a server.
  4. Click Next>>.
  5. Specify a host name or IP address in the second of the two fields next to Server Address. You can leave the value as *:*, where the first asterisk (*) indicates the IP address of the current machine and the second indicates any available port number.
  6. Specify the location for files output by the Directory Server, such as trace and dump diagnostics files, in System Directory. This directory cannot be shared between enterprise servers. The default is \es-name where es-name is the name of the enterprise server.

    If you specify a directory in this field, that directory must exist; Enterprise Server does not create it for you.

  7. Specify the start-up configuration you want in the fields under Startup Options.
  8. Specify any trace flags you want to be set in the fields under Trace Flags.
  9. Specify any configuration information the server requires in Configuration Information For information on what you can specify, see the section Configuration Information in the chapter Servers in your Configuration and Administration Guide.
  10. Specify a text description of the server in Description (optional).
  11. Click Add.
Parent topic: Creating and Configuring Enterprise Server Instances
Parent topic: Work with Servers


To Change the Number of ES licenses

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the enterprise server instance for which you want to change the number of licenses.

    The Server > Properties > General page is displayed.

  2. Specify the new number of licenses in Requested Licenses.
  3. Click OK.
Note:

If the status of the enterprise server instance is "Started", you can also change the number of licenses by clicking Details in the Current status column, then on the Enterprise Server > Control page, specifying the new number in Requested licenses and clicking Update. The Directory Server allocates additional licenses requested immediately, up to the number available. It removes any unwanted licenses immediately. However, any change you make here is temporary only; after you stop the server, the number of processes reverts to the number set on the Server > Properties > General page.

Parent topic: Creating and Configuring Enterprise Server Instances
Parent topic: Work with Servers


To Copy an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note:

When you copy an enterprise server instance to another of the same working mode, the default behavior is to copy all the objects associated with it - communications processes, service listeners, services, request handlers and implementation packages. If the working mode of the new enterprise server instance is different from that of the existing server, the copy process cannot copy deployed services (that is, services that have an associated package and handler). Therefore, where the existing server has deployed services and you want the copy to have a different working mode, you must check Do not copy deployed services and packages.

  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the enterprise server instance that you want to copy.
  2. On the Properties > General page click Copy.
  3. Specify the name of the new server in Name under ...to new server...
  4. Click the Working Mode checkbox if you want to change the working mode for the new server.
  5. In Initial Communications Processs Address under ...to new server... specify a host name or IP address to replace the first asterisk (*) and a port number to replace the second asterisk. You can leave the value as *:*, where the first asterisk (*) indicates the IP address of the current machine and the second indicates any available port number.
  6. Click Do not copy deployed services and packages if you do not want to copy the deployed services and packages to the new server.
  7. Click OK.
Parent topic: Creating and Configuring Enterprise Server Instances
Parent topic: Work with Servers


To Delete an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server that you want to delete.
  2. Click Delete on the Properties > General page.
  3. Click OK on the Confirmation page.
CAUTION:

Deleting a registered server might cause application connection errors and loss of data.

Parent topic: Creating and Configuring Enterprise Server Instances
Parent topic: Work with Servers


To Delete a CCI Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

Deleting a registered server might cause application connection errors and loss of data.

  • Click Delete to the left of the server name on the Home page.
Note:

Only CCI servers are deleted in this way. CCI servers are identified by type MFCCI.

Parent topic: Creating and Configuring Enterprise Server Instances
Parent topic: Work with Servers


To Export Server Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server for which you want to change the number of instances.

    The Server > Properties > General page is displayed.

  2. Click Export.
  3. On the Export Server page, specify the location to which you want to save the server information in Target directory. This defaults to $COBDIR/etc/mfds.
  4. Click OK.

    If the location you specified contains previously exported information, you will now be presented with a confirmation page. This displays details of the information currently held in the target location. The details shown include: any Enterprise Servers, the Security Manager pool, and Security Manager lists and security configuration settings.

    If you confirm the export, existing information in the target location will be overwritten.

Note:
  • When you export server information, you create a backup copy of the server definition.
  • If you specify a directory that does not exist, it will be created if the directory containing it exists; otherwise it will not be created and the export will fail.
  • You can export all server definitions in the MF Directory Server repository. See To export the repository.
  • For instructions on importing server definitions, see To import a repository.
Parent topic: Creating and Configuring Enterprise Server Instances


Connecting to a Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.

From Enterprise Server Administration you can connect to the enterprise server instance and access the details of the server that you want to monitor.

Provided the server has been started, you can access the Enterprise Server Monitoring and Control (ESMAC) screen from the server's Details screen.

You can return to Enterprise Server Administration by clicking Home from the left pane of these screens.

  • To start an enterprise server instance
  • To stop a server Instance
  • To Edit an Enterprise Server Instance
  • To Log On to Enterprise Server Administration
  • To Log Off from Enterprise Server Administration
  • Using Start and Stop Scripts
Parent topic: Configuring and Administering Enterprise Server Instances


To start an enterprise server instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Enterprise Server Administration Home page, find the row for the server that you want to start, and click Start in the Current Status column.

    A screen is displayed showing the server details and security configuration information. This screen also gives you the option of specifying operating system and Enterprise Server security credentials to be used.

  2. Click OK.

    The Enterprise Server Administration Home page is displayed, and progress is shown in the in the Status Log column. If you have Show local console checked on the Edit Server page, the enterprise server console daemon window appears indicating the progress.

  3. After a few seconds click Refresh on the Home page.

    When the server starts, the value in Current Status changes to Started.

Note:

If the server does not start for a prolonged time the reason might be that it has encountered an unrecoverable error but the server process remains active. In this case click Details to go to the Server > Control page, then click Stop Server to shut down the unsuccessful server process. Alternatively it might have encountered an unrecoverable error during the startup process and shut down without informing the Directory Server. In this case you can restart it using Start Server on the Server > Control page.

Parent topic: Connecting to a Server Instance
Parent topic: Work with Servers
Related information
Configuring and Starting Transaction Data Collection
Viewing HSF Information in ESMAC


To stop a server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This procedure describes how to stop an enterprise server instance from the Enterprise Server Administration screen. You can use the server shut down process if you need more control over the process, or you want to produce a system dump.

  1. In the table of servers on the Home page of Enterprise Server Administration, find the row for the server that you want to stop, and click Stop in the Current Status column.

    A screen is displayed indicating the server details and security configuration information. This screen also gives you the option of specifying operating system and Enterprise Server security credentials to be used. For more about security credentials, see the help section on Enterprise Server security.

  2. Click OK.

    The Home page of Enterprise Server Administration is displayed, and the Status Log column displays server termination progress messages. If you have Show local console checked on the Edit Server page, the enterprise server console daemon window appears, showing progress messages.

  3. After a few seconds click Refresh on the Home page.

    The value in Current Status changes to "Stopped".

Note: If the server remains in the "Stopping" state for a prolonged time the reason might be that it has encountered an unrecoverable error during the shutdown. You can force a shutdown by clicking Details to go to the Server > Control page, then clicking Force Stop. Alternatively it might have encountered an unrecoverable communications error and shut down without informing the Directory Server. In this case you can restart it using Start Server on the Server > Control page.
Parent topic: Connecting to a Server Instance
Parent topic: Work with Servers


To Edit an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server that you want to edit.
  2. The top row of tabs displays Server, Listeners, Services, Handlers and Packages. Select the tab for the type of attribute you want to edit.
  3. Click the Edit button for each listener, service, handler or package that you want to edit.
  4. Update the attributes as required.
  5. Click OK.
  6. Click the Server tab.
  7. Click one of the tabs: Properties, Control, and Diagnostics to select the type of attribute you want to update. The Properties page is the default.
  8. What you do next depends on what tab you selected in the previous step:
    • If you selected Properties, click one of the tabs General, XA Resources, Scripts, Permissions and Security to select the page containing the attributes you want to update. The General page is the default.
    • If you selected Control, you see the Control page. If the server is not running all you see is a message giving the server state. If the server is running, the number and type of processes will be displayed. Click ES Monitor & Control... to display server information and diagnostics.
    • If you selected Diagnostics, click one of the tabs Trace, Dump, ES Console and CS Console to select the page containing the attributes you want to update. The Trace page is the default.
  9. Update the attributes on the page as required.
  10. Click OK.
Parent topic: Connecting to a Server Instance
Parent topic: Work with Servers


To Log On to Enterprise Server Administration

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Log On on the menu on the left-hand side of the Enterprise Server Administration home page.
  2. Specify your user ID in User ID.
  3. Specify your password in Password.
  4. Click OK.
  5. Click Continue on the Welcome page.
Note:

You can see the Log On option only if user access is restricted and you are not currently logged on.

Parent topic: Connecting to a Server Instance
Parent topic: Log On and Off


To Log Off from Enterprise Server Administration

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Click Log Off on the menu on the left-hand side of an Enterprise Server Administration Web page.
    Note: You can see the Log Off option only if user access is restricted and you are currently logged on.
Parent topic: Connecting to a Server Instance
Parent topic: Log On and Off


Using Start and Stop Scripts

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can supply start and stop scripts to take additional actions before or after starting or stopping an enterprise server. You must include the casstart command in your start script, and the casstop command in your stop script. If you omit them the server will not actually be started or stopped.

The Directory Server sets some environment variables in the scripts' environment, which you can use in your scripts:

ES_HOME | Server work directory (location of log files); this comes from the System Directory field on the Add Server or Edit Server > Properties > General page.
ES_SERVER | Server name (note that Enterprise Server will use this as the server name if no -r switch is specified on casstart or casstop).
MFDS_PORT | The port on which the Directory Server listens (usually 86).

If you specified a location for the server work directory, rather than taking the default, during the installation process or when you ran the casperm command, that location overrides the location specified in the System Directory field in the server configuration. The result is that ES_HOME will not be set correctly for startup and shutdown scripts. We recommend using the System Directory field rather than specifying a non-default location during installation or with the casperm command for this reason.

For example, the start script could be used to set environment variables for the server, as follows;
#! /bin/ksh
export MY_VARIABLE=value
# start the enterprise server
echo Enterprise Server $ES_SERVER is starting
casstart

where value is the value of the environment variable.

If your stop script contains commands that should only be executed after the server has stopped completely, it should pause after executing casstop until thecascd process for that server has exited. This is because the casstop command returns before the server has actually finished shutting down. You can do this by querying the status of the cascd process, the enterprise server console daemon. For example:

#! /bin/ksh
 # Get the PID of the cascd process
 Cascd=$(ps -ef | awk '$8~/cascd/ && $9~/.rESDEMO/ {print $2}')

 # Begin shutdown
 casstop

 # Wait for the cascd process to exit
 while ps -p $Cascd > /dev/null; do sleep 1; done

Then you could back up the log files or perform other tasks that should only be started after the server finishes shutting down.

When you click the server's Start or Stop button, the commands that you specify are used to generate a UNIX shell script, which is then executed.

You can also create an "On server not responding" script. This script will be executed when all of the running communications processes for a server have entered the "Not Responding" state. That might indicate that the server is hung or has crashed, or it might result from network connectivity problems between the Directory Server and the enterprise server (if they run on different systems). You can use this script to notify a system administrator of the problem.

You specify start, stop and "On server not responding" scripts on the Edit Server > Properties > Advanced page.

Parent topic: Connecting to a Server Instance


Administering Enterprise Server Instances using ESMAC

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server Monitor and Control (ESMAC) enables you to view and control enterprise server instances, and the services, packages, and handlers that run on them.

Note: The enterprise server instance to administer must be started before the ESMAC screen becomes available.

From ESMAC, you can:

  • Monitor and control an enterprise server instance, including service execution processes, services, packages, and so on.
  • Monitor the current activity and performance of enterprise server instances and applications, and monitor the trends in that activity and performance.
  • Obtain diagnostic information (dumps and traces) for your applications.

ESMAC enables you to define who can use ESMAC, and the permissions they have to view and update resources. For more information on setting up ESMAC users, see the section Security.

  • To Start ESMAC for an enterprise server instance
  • To Shut Down a Server from ESMAC
  • Viewing Enterprise Server Instance Details
  • The ESMAC User Interface
  • Defining Enterprise Server Instance Administrators
  • Managing an Enterprise Server Instance's SEPs
  • Interacting with Services
Parent topic: Configuring and Administering Enterprise Server Instances


To Start ESMAC for an enterprise server instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The enterprise server instance must be started before the ESMAC screen becomes available.

  1. Open the Enterprise Server Administration user interface.
  2. In the list of servers next to the server to access, click Details in the Status column to display the details screen for the enterprise server instance.
  3. On the enterprise server instance details screen, click the ES Monitor & Control button.

    The ESMAC screen is displayed.

Parent topic: Administering Enterprise Server Instances using ESMAC
Parent topic: Administer a Server Using ESMAC


To Shut Down a Server from ESMAC

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can shut down a server from the Monitor and Control (ESMAC) screen. This allows you more control over the shutdown process, and you can specify that the shut down process produces a dump.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To shut down a server

  1. Click Control.
  2. If you want a dump, check Dump. A system dump is produced at the beginning and at the end of the final stage of system shutdown.
  3. If you want an immediate shutdown, check Immediate. If you force an immediate shutdown, you will see the "The page cannot be displayed" error, as there is no longer a server to connect to.
  4. Click Shutdown.
Parent topic: Administering Enterprise Server Instances using ESMAC


Viewing Enterprise Server Instance Details

Restriction: This topic applies only when the Enterprise Server feature is enabled.

ESMAC provides information about the enterprise server you are currently viewing. Use the tabs at the top of the page to access the information that you want.

For example, click the Server tab to display the Server Information page. The Server Information page provides information that enables you to monitor the operation of the enterprise server, providing details on:

  • Times - such as the time the enterprise server was started, and the time for which it has been available.
  • Counts - such as the number of services, dumps, and trace blocks.
  • Sizes - such as maximum number of tasks enabled on the server, the amount of memory available, and the size of diagnostic files.
  • States - such as the dump state and the currently set dump datasets.
  • Activity - average times taken to complete tasks.

The information provided enables you to quickly determine the state of the server. For example:

  • The Activity information enables you to see whether any services are behaving in unexpected ways by, for example, taking more time to complete than you expect.
  • The State information provides information on the current dump state, showing, for example, that a dump is taken when the system abends, but not when the service abends.

Based on the information presented on this page you can make changes using other ESMAC pages that you can access using the tabs.

Parent topic: Administering Enterprise Server Instances using ESMAC


The ESMAC User Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The ESMAC interface is displayed using a browser. You can, therefore, monitor and control enterprise server instances across the Internet, or your intranet, from a browser.

When you first view ESMAC, the Server Information page is displayed, as shown below:

Figure 1. ESMAC Server information page
ESMAC Server information page

ESMAC enables you to:

  • Obtain information about the server you are currently connected to.
  • Monitor services occurring on the server.
  • View and change various parameters associated with server, such as the number of service execution processes, the active diagnostic datasets, and any trace control flags set.
  • View information about service execution processes (SEPs), stop SEPs and obtain trace information for them.
  • View information about client processes running on the server.
  • View console logs, and dump and trace information.
  • View information about the services, packages and request handlers defined on the server.
  • Add, delete and change the permissions of users who can administer servers.
  • View the environment variables associated with the server.
  • Login as an administrator.

The ESMAC interface is split into two areas:

  • A menu, in a sidebar on the left side of the page, which provides buttons with which you can control ESMAC.
  • The main body of the page, which displays the monitor and control information. The information and controls available here depend on the button you click in the menu.
  • Sidebar
  • Body
  • Status Line
  • Refreshing a Page
Parent topic: Administering Enterprise Server Instances using ESMAC


Sidebar

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The ESMAC menu appears in a sidebar on the left side of the page. You see only the menu options that are appropriate to your permission level.

Parent topic: The ESMAC User Interface


Body

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Control and monitor information is presented in the body of the page.

The body of the page changes when you click a button in the menu. The body of the page usually contains one or more controls, which you can use to enter and modify information required by the enterprise server instance.

Parent topic: The ESMAC User Interface


Status Line

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The status line appears at the top of the page. This line tells you:

  • The enterprise server you are connected to.
  • The server on which the enterprise server is running.
  • Your user name.
  • The date and time at which the current page was displayed.
Parent topic: The ESMAC User Interface


Defining Enterprise Server Instance Administrators

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic describes how to set up the users who can access Enterprise Server administration, and set the appropriate permissions for those users.

The default security access configuration depends on how your system is set up. A system can be set up with or without the special user mfuser defined:

  • If mfuser is not defined, by default all users can perform any action.

    For an installation used for development, we recommend that you do not configure an mfuser.

  • If mfuser is defined, the default security level is the same as that defined for mfuser.

    For an installation used for production, we recommend that you do configure an mfuser, and give mfuser only minimum privileges.

You create user names, passwords, and set permissions using the Users page.

You can see which administrators are currently set up by accessing the ESMAC screen and clicking Users. This displays the Users page, which lists all users. Click Details on the Users page to get detailed information on a user's permissions.

If you do not have the required read or update permissions, the options available to you in ESMAC are limited. You can only:

  • View server information. See the section Server Information for details.
  • Monitor the performance. See the section Monitoring Services for details.
  • View environment variables. See the section Environment Variables for information.
  • Change to a different user.
Parent topic: Administering Enterprise Server Instances using ESMAC
Related information
Enterprise Server Execution Control Under Windows


Managing an Enterprise Server Instance's SEPs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can view details of the SEPs running in an enterprise server instance using ESMAC. You do this using the Control page, which can be displayed by clicking Control on the ESMAC menu.

For example, you can view various information about an enterprise server instance, including the dump state. If you wanted to change the dump state, you would use the Control page.

The Control page enables you to veiw the following details:

  • The number of SEPs running on the enterprise server instance.
  • Dump and trace parameters, including the size of the auxiliary trace and dump file, the datasets to be used for dumps and traces, and so on.
  • Whether programs are reloaded each time they are invoked.
  • The trace control flags set.
  • The size of the data blocks passed across shared memory for HTTP output.
  • The timeout value that will be used for all users of the enterprise server instance who do not have a timeout value set for their user ID.

You can also shut down the enterprise server instance from this page, and you can obtain a dump of the server on shutdown.

  • About Service Execution Processes
  • To Change the Number of SEPs
Parent topic: Administering Enterprise Server Instances using ESMAC


About Service Execution Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Service execution processes are provided within an enterprise server. COBOL applications are executed within these service execution processes. For more information on service execution processes, see the section Service Execution Processes in the chapter Configuration in your Enterprise ServerConfiguration and Administration Guide.

You can view information on the SEPs running on an enterprise server by displaying the SEPs (Service Execution Processes) page. To do this, click SEPs in the menu.

The SEPs (Service Execution Processes) page displays details for all SEPs on the current enterprise server, including:

  • The process ID
  • The type of SEP
  • The task number
  • The number of services that have run in this SEP

You can also terminate SEPs and create and view traces for SEPs.

Parent topic: Managing an Enterprise Server Instance's SEPs


To Change the Number of SEPs

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server for which you want to change the number of instances.

    The Server > Properties > General page is displayed.

  2. Specify the new number of instances in Service execution processes.
  3. Click OK.
Note: If the status of the server is "Started", you can also change the number of service execution processes by clicking Details in the Current status column, then on the Enterprise Server > Control page, specifying the new number in Requested service execution processes and clicking Update. The new processes will take a few seconds to appear in the list. However, any change you make here is temporary only; after you stop the server, the number of processes reverts to the number set on the Server > Properties > General page.
Parent topic: Managing an Enterprise Server Instance's SEPs
Parent topic: Work with Servers


Interacting with Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Programs running as services in an enterprise server can include ACCEPT FROM CONSOLE and DISPLAY UPON CONSOLE statements. When execution reaches a DISPLAY UPON CONSOLE statement, the display text is displayed in the console log, and the service continues. When execution reaches an ACCEPT FROM CONSOLE statement, the service pauses and asks for input using pages in ESMAC. You must provide the input in order for the service to continue executing.

  • To Reply to an ACCEPT FROM CONSOLE Statement
Parent topic: Administering Enterprise Server Instances using ESMAC


To Reply to an ACCEPT FROM CONSOLE Statement

Restriction: This topic applies only when the Enterprise Server feature is enabled.

  1. Click Reply in the menu. You see a page listing all the current pending ACCEPTs. They are identified by PID (Process ID).
  2. Click Select next to the process that you want to reply to.
  3. Specify your reply in the Enter field, then click Reply just above it.
Parent topic: Interacting with Services


Stopping and Restarting an Installation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before stopping the Directory Server or shutting the machine down, you should stop all enterprise server instances that are running. When you stop the Directory Server using Enterprise Server Administration, there is an option to stop all servers first.

On system restart, unless Restore Servers on Startup on the Configure Options page is checked, the Directory Server does not automatically start any enterprise server instances that were not stopped before shutdown (and so are still marked as "Started" in the Directory Server repository). If the Server Monitor is enabled on the Configure Options page it will check whether these enterprise server instances are still active, and will mark them as "Not Responding" in the Enterprise Server Administration servers table on the Home page. Each enterprise server instance will then need to be restarted manually. You can do this by clicking Details and then clicking Start Server for each server.

If Restore Servers on Startup is selected, when Directory Server is restarted, it reads the list of servers that were previously marked as started, checks to see if they are running, and if not, attempts to restart them.

Parent topic: Configuring and Administering Enterprise Server Instances


Using the Command-line Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A number of commands are available for administering servers. You can run these commands from an application command prompt. For example to access the Windows application command prompt from a Micro Focus Visual COBOL installation, from the Start menu, select: > Tools > Product Name Command Prompt.

  • casdump
    Forces a system dump.
  • casdup
    Formats a system dump or auxiliary trace so that it is suitable for analysis.
  • casperm.sh
    Prepares Enterprise Server for use.
  • casstart
    Starts an enterprise server.
  • casstop
    Stops an enterprise server.
Parent topic: Configuring and Administering Enterprise Server Instances


casdump

Forces a system dump.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

casdump [/res-name]
        [/d]
        [/f]
        [/i]
        [/b]
        [/udump-code]

Parameters:

/res-name | Name of the enterprise server to dump. Defaults to ESDEMO
/d | Do not lock shared memory
/f | Dump the FAQE chain
/b | Dump shared memory as a block
/udump-code | Sets the dump code for the dump

Dependencies:

To use this command:

  • You must have started the enterprise server named with the /r flag first.
  • You must be running under the same user ID as the enterprise server named with the /r flag. If the Directory Server was started as a system service, and the enterprise server was started using the Administration interface, then the enterprise server is probably running under the LOCAL_SYSTEM user ID, and this command will not work. For more information see the section Starting and Stopping the Directory Server in the chapter Introduction to Enterprise Server Administration in your Enterprise Server Configuration and Administration Guide.

Comments:

On UNIX you can use a dash (-) before a parameter as an alternative to a forward slash (/).

Parent topic: Using the Command-line Interface
Parent topic: Administration and Configuration Commands


casdup

Formats a system dump or auxiliary trace so that it is suitable for analysis.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

casdup [/res-name]
       [/a|/b|/x]
       [/c]
       [/d]
       [/ffile-name]
       [/ifile-name]
       [/l]
       [/n]
       [/mxx{,xx}...]
       [/pnn{,nn}...]
       [/snnnnnn]
       [/w]
       [/0]
       [/1]
       [/2]
       [/3]
       [/4]
       [aux]

Parameters:

/res-name | Name of the enterprise server that owns the dump. Defaults to ESDEMO
/a | Use the A data set (default)
/b | Use the B data set
/x | Use the X data set (for external dumps produced by casdump /d)
/c | Display only the application program information entries
/d | Display module IDs
/ffile-name | The name of the output formatted dump file
/ifile-name | The name of the input trace file. Overrides /a, /b, /r, /x and aux
/l | List summary information only
/n | Omit page headers
/mxx{,xx}... | The module IDs to be included in the trace
/pnn{,nn}... | The process IDs to be included in the trace
/snnnnnn | Split output after every nnnnnn lines
/w | Wide trace format
/0 | Module/transaction trace
/1 | /0 level trace plus API
/2 | /1 level trace plus RTS and EXTFH trace
/3 | All formatted trace
/4 | All trace (default)
aux | Format an auxiliary trace dump data set. The default is that a system dump is formatted

Dependencies:

You must have created a system dump or auxiliary trace before you can issue casdup.

Comments:

You can use a dash (-) before a parameter as an alternative to a forward slash (/).

Parent topic: Using the Command-line Interface
Parent topic: Administration and Configuration Commands


casperm.sh

Syntax:

casperm.sh

Parameters:

None

Comments:

The casperm.sh command asks you a series of questions. For further information see the topic To run casperm

Parent topic: Using the Command-line Interface
Parent topic: Administration and Configuration Commands


casstart

Starts an enterprise server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

casstart [/res-name] [/uusername] [/ppassword] [/cgroup] [/w]

Parameters:

/res-name | Name of the enterprise server to start. Defaults to ESDEMO
/uuserid | An authorized user. This user must exist within the security domains of both: the enterprise server and MF Directory Server. That is, the security configuration for both enterprise server and Directory Server must be able to verify the user credentials supplied. Note that enterprise server and Directory Server may be using different security managers. Therefore, it may be necessary that the user is defined in more than one security repository. In order to update Directory Server status information, within the Directory Server domain, the user must have modify permission on the appropriate enterprise server resource within the Servers resource class. In order to successfully run the casstart command, within the enterprise server's security domain, the user must have alter permissions on the casstart resource within the OPERCMDS resource class. Note: This is only required if you have configured security.
/ppassword | The password for the user
/cgroup | The sign-on group for the user. By default, when a user requests access to a resource, some external security managers will only apply rules that refer to that user and the user's current sign-on group. If this option is not specified, the user is signed on with a default group as determined by the security manager.
/wdelay | The delay (in seconds) to wait before starting the region. If you omit the /w option the system does not wait, or if you specify /w without delay the system waits for 15 seconds.

Comments:

On UNIX you can use a dash (-) before a parameter as an alternative to a forward slash (/).

The command line utilities: casstart, casstop, casfile, casout, and cassub can be invoked by program using the call interface and passing the command line parameters to the call. For instance, we might use the following to start a server:

01 ws-cmd-parms.
     05 ws-cmd-len         pic x(02) comp-x.
     05 ws-cmd-value     pic x(1024).
......
......
......
      *> Start up the Server
      move 1                to ws-cmd-len
      move low-values  to ws-cmd-value
      string "-rMyRegion" delimited by size
               " -uSYSAD -pSYSAD /w" delimited by size
               into ws-cmd-value with pointer ws-cmd-len
      end-string
      subtract 1 from ws-cmd-len
      call 'casstart' using ws-cmd-parms end-call
......
......

When used on platforms that support running both 32-bit and 64-bit applications, casstart checks its environment to determine whether to start the Enterprise Server in 32-bit or 64-bit mode. If the server's working mode (as specified when it was created) does not match the mode specified by the environment, casstart will fail and issue an appropriate message. On Unix platforms, you choose the mode by setting the COBMODE environment variable to 32 or 64 as appropriate. On Windows platforms, you can choose the environment by choosing the relevant command prompt from the Start menu.

Parent topic: Using the Command-line Interface
Parent topic: Administration and Configuration Commands


casstop

Stops an enterprise server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

casstop [/res-name] [/sprototype:host:WebServiceport] [/lserver-name] [/i] [/w] [/f] [/uuserid] [/ppassword] [/ggroup]

Parameters:

/res-name Name of the enterprise server to stop. Defaults to ESDEMO. To use this option:
  • You must have started the enterprise server named with the /r flag first.
Note: When calling this utility from a Web service (that is, when you are running the utility within a SEP) you cannot use the /r option to connect to the server. Where this is the case, you must use the /s or /l options to connect to the server.
or:
/sprototype:host:WebServiceport | Location of the Web Services listener for the enterprise server to be stopped. For example, /stcp:localhost:9003
or:
/lserver-name | Name of the enterprise server. This differs from the /s option, in that it performs a lookup to locate the Web Service for the enterprise server
/i Immediate shutdown

When you use this option, all SEPs and all in-progress transactions are immediately terminated, and the PLT shutdown is not run. The region then terminates normally.

/w | Wait for shutdown to be completed
/f Force a shutdown. This option cannot be used in conjunction with /s or -/l

When you use this option, all processes are killed and the region stops with no shutdown processing.

/uuserid An authorized user. This user must exist within the security domains of both: the enterprise server and MF Directory Server. That is, the security configuration for both enterprise server and Directory Server must be able to verify the user credentials supplied. Note that enterprise server and Directory Server may be using different security managers. Therefore, it may be necessary that the user is defined in more than one security repository.

In order to update Directory Server status information, within the Directory Server domain, the user must have modify permission on the appropriate enterprise server resource within the Servers resource class. In order to successfully run the casstop command, within the enterprise server's security domain, the user must have alter permissions on the casstop resource within the OPERCMDS resource class.

Note: This is only required if you have configured security.
/ppassword | The password for the user
/cgroup The sign-on group for the user. By default, when a user requests access to a resource, some external security managers will only apply rules that refer to that user and the user's current sign-on group.

If this option is not specified, the user is signed on with a default group as determined by the security manager.

Note:
  • Options /r, /s, /l are alternative ways of identifying the enterprise server to be stopped and are mutually exclusive.
  • Where an external security manager is configured for the enterprise server, a userid and password must be supplied when stopping it.

Comments:

On UNIX you can use a dash (-) before a parameter as an alternative to a forward slash (/).

Many of the command line utilities, including casstart, casstop, casfile, casout, and cassub, can be invoked by program using the call interface and passing the command line parameters to the call. For an example, see casstart.

Parent topic: Using the Command-line Interface
Parent topic: Administration and Configuration Commands


Configuring Client-Server Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A communications process is the component of an enterprise server instance that handles communications between clients and the enterprise server instance. It contains a number of service listeners. An enterprise server instance is created with one communications process, but you can add more.

A service listener accepts incoming client requests on behalf of services. A service can have multiple listeners, and a listener can accept client requests on behalf of multiple services.

  • About Communications Processes
  • Considerations When Configuring Communications Processes
  • Displaying Communications Process and Listener Information
  • Securing Communications
  • Configuring Communications Processes
  • Configuring Listener Conversation Types
  • Configuring Listeners
Parent topic: Enterprise Server configuration and administration


Considerations When Configuring Communications Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Multiple communications processes

If you are configuring multiple communications processes for an enterprise server instance, you need to consider the following:

  • You can configure different communications processes for different types of communications, for example, one communications process for TN3270 traffic and another for Web Services and ESMAC. With this sort of configuration, a failure in one communications process does not disrupt others, so other types of communications are not affected.
  • You can also run multiple communications processes for the same kinds of clients, configuring some clients to connect to one port and other clients to connect to a different port.
  • Communications processes cannot share ports. If you use fixed ports for your communications listeners, each listener must have a different port assigned to it if they will be running at the same time.
  • There is no support in Enterprise Server for failing conversations over from one communications process to another.

Other considerations

  • Some clients, such as Rumba, can be configured to try a series of ports when establishing a connection. Other clients may have to be configured manually to try a different communications process if the main one is not responding.
  • COBOL Web Services clients can be configured to search for an available enterprise server listener, rather than a specified port number.
Parent topic: Configuring Client-Server Communications


Displaying Communications Process and Listener Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can see the information held in the repository for communications processes and listeners by clicking Details on the Home page in the Communications Process column for the enterprise server instance that you are interested in. The communications process and listener table is shown below.

Figure 1. Communications Processes and Service Listeners Table
Communications Processes and Service Listeners Table

The information for a communications process is as follows:

  • Auto-start - whether or not the communications process is started automatically when the enterprise server instance starts.
  • Listeners - the number of listeners owned by this communications process.
  • Process ID - the process ID of this communications process. This is present only when the communications process is running.
  • Control Channel Address - this is an internal address used by enterprise server instance components for communications. An asterisk at the end of the IP address or port number indicates that this part of the address is not fixed but supplied by the host system on startup.
  • Status information - you can see the current status and the time of the last status change.
  • Status log - this supplies information about the most recent event that occurred for this communications process.
  • Version - this is the version number of the communications process software.

Communications processes do not have names; instead they have sequence numbers. The communications process that is automatically created when you add a new enterprise server instance is Communications Process 1, and any further communications processes that you create are numbered in ascending order of creation. When you delete a communications process, existing communications processes are not renumbered, however, the next communications process you create will use the same number as the process that was deleted - the lowest available number.

The information for a listener is as follows:

  • Name
  • Address - this is the network address on which the listener listens for incoming client requests. An asterisk at the end of the IP address or port number indicates that this part of the address is not fixed but supplied by the communications process on startup.
  • Status information - you can see the current status and the time of the last status change
  • Status Log - this supplies information about the most recent event that occurred for this listener
  • Conversation Type - this indicates what type of client requests the listener handles. Possible values are:
    • Web Services and J2EE for SOAP or J2EE requests
    • Web for World Wide Web (HTTP) requests; Enterprise Server uses a Web listener for service deployment
    • Fileshare for Fileshare client requests
    • Custom for any other type of requests
  • Custom configuration data - for more information see the section Configuration Information
  • Description

Listener display filters control how much listener information you can see. These appear just above the information for the first communications process. There are three listener display filters:

  • Process (communications process)
  • Conversation type
  • Status

Each has a number of options that vary depending on the field; for example the Process filter allows you to select to see no listener details, all listener details, or listener details for a particular communications process, while the Status filter allows you to see all listener details regardless of status or just listener details for listeners with a specifc status:

For example, to see listener details for communications process 2, choose 2 in Listener Display Filters Process; to see only Web Services and J2EE listeners, choose Web Services and J2EE in Listener Display Filters Conversation Type; to see all listener details choose All in all three filters. Use all the filters in combination to achieve the maximum control over the level of detail you see.

When you first see the Communications Process and Listeners table, the Process filter is set to None and the other filters are set to All.

Parent topic: Configuring Client-Server Communications
Related information
Configuration Information


Securing Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

There are a number of additional configuration options, for logging and setting an SSL passphrase, that can be set in the file mf-server.dat, located in $COBDIR/etc . These are mostly options that require setting before the Micro Focus Communication Server (MFCS) contacts the MF Directory Server. In the case of logging, this can be useful where there are problems with the connection between MFCS and MFDS. For instructions on the use of mf-server.dat to configure logging for MFCS, see the topics on securing communications in the Security section, or see the topic Communications Process Log Files in the Troubleshooting section.

Parent topic: Configuring Client-Server Communications


Configuring Communications Processes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Your responsibilities as administrator include:

  • Adding communications processes as required, by copying and editing existing ones
  • Updating and deleting communications processes as required
  • Starting and stopping communications processes
  • Adding, updating and deleting listeners as required
  • Associating listeners with services and disassociating them
  • Starting and stopping listeners
Note: You can use the Configuration Information field on the Edit Communications Process page, and the Add Listener and Edit Listener pages for configuration data specific to a communications process or a listener.
  • Editing Communications Settings
  • To Edit a Communications Process
  • To Copy a Communications Process
  • To Delete a Communications Process
  • To Start a Communications Process
  • To Stop a Communications Process
  • To View Communications Processes and Listeners for an Enterprise Server Instance
  • To View Statistics for a Communications Process
Parent topic: Configuring Client-Server Communications


Editing Communications Settings

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Configuration Information field on the Edit Communications Process page can contain the following sections and settings:

[CCI]
timeout-grain=timeout-grain-number-of-seconds
[ISC]
listener-wait=listener-wait-number-of-seconds
[listeners]
logging=logging-level
[MFCC]
trace=trace-setting
[threading]
limit=number-of-threads

The parameters are explained below.

  • timeout-grain
    Specifies the CCI timeout in seconds. Any MFCS timeout will be rounded up to a multiple of this value.
  • logging
    Enables additional logging when starting listeners.
  • trace
    Controls common client (MFCC) tracing, in conjunction with the MFCC configuration file.
  • limit
    Specifies the thread limit.
Parent topic: Configuring Communications Processes


timeout-grain

Specifies the CCI timeout in seconds. Any MFCS timeout will be rounded up to a multiple of this value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

timeout-grain=timeout-grain-number-of-seconds

Properties:

Default: 5 seconds

Comments:

The communications process (MFCS) lets each conversation and listener set its own timeout value for receiving data, but because MFCS runs as part of CCI, and CCI only maintains one global timeout value for the whole process, the granularity of MFCS timeout values is limited by the CCI timeout setting. Setting a larger value than the default will make MFCS timeouts less precise, but will reduce CPU consumption, interrupts, and other factors, improving performance.

Parent topic: Editing Communications Settings


logging

Enables additional logging when starting listeners.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

logging=logging-level

Parameters:

logging-level Can be one of:
0 | No extra logging (default)
1 or Yes | Basic logging, which includes extra CCI error information
2 | Also log CCI loading and configuration, and listener address information
3 | Also log SSL configuration
Default: 0

Properties:

Default: 0
Parent topic: Editing Communications Settings


trace

Controls common client (MFCC) tracing, in conjunction with the MFCC configuration file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

trace=trace-setting

Parameters:

trace-setting
One of:
0 | Disable MFCC tracing
any non-zero value | Enable MFCC tracing during MFCS startup

Properties:

Default: 0

Comments:

MFCC tracing is off by default but can be enabled in the configuration file, which by default is mf-client.dat, located in $COBDIR/etc , but you can create your own configuration file of any name or location and identify it using the MFC_CONFIG environment variable. MFCS uses MFCC during startup to verify that its control channel is working. If MFCC tracing is enabled in the configuration file, you can set this option to “0” to disable MFCC tracing in MFCS. Alternatively, you can set it to a non-zero value to enable MFCC tracing during MFCS startup, to diagnose a failure there.

Parent topic: Editing Communications Settings


limit

Specifies the thread limit.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

limit=number-of-threads

Properties:

Default: 2000 on Windows and 200 on UNIX

Comments:

MFCS limits the number of threads it will try to start, in order to avoid exceeding system limits. Currently, MFCS uses one thread for each active conversation, so this limit directly affects the number of simultaneous conversations. Note that the operating system might not allow MFCS to actually create as many threads as the number you set.

Parent topic: Editing Communications Settings


To Edit a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to edit.
  3. On the Edit Server - Listeners page click Edit to the left of the row for the communications process you want to edit.
  4. Update the attributes of the communications process as required.
  5. Click OK.
Note: You can make some changes to a communications process on the Edit Server - Listeners page: toggle Auto-start, and stop and start the communications process.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To Copy a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to copy.
  3. On the Edit Server - Listeners page click Copy at the top right-hand side of the area that shows the details of the communications process you want to copy.
  4. In Control Channel Address specify a host name or IP address to replace the first asterisk (*) and a port number to replace the second asterisk. You can leave the value as *:*, where the first asterisk (*) indicates the IP address of the current machine and the second indicates any available port number.
  5. Check Auto-start if you want the new communications process to be started automatically when the enterprise server starts or, if the enterprise server is already running, after it is created. It is checked by default.
  6. Click OK.
Note: When you copy a communications process, you also copy all the listeners associated with it; the new communications process has exactly the same number and type of listeners as the original, with the same names. You might want to edit the names to reduce confusion.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To Delete a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to delete.
  3. On the Edit Server > Listeners page click Delete at the top right-hand side of the area that shows the details of the communications process you want to delete.
  4. Click Delete on the confirmation page.
Note: If an enterprise server has only one communications process, you cannot delete it.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To Start a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking
    expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to delete.
  3. On the Edit Server - Listeners page click Start at the top right-hand side of the area that shows the details of the communications process you want to start.
Note:
  • You can start a communications process only if:
    • The enterprise server is started.
    • The status of the communications process is "Stopped".

    When an enterprise server starts, any stopped communications processes are started automatically if Auto-start is set on.

  • When a communications process starts, all the service listeners it owns start too.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To Stop a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to delete.
  3. On the Edit Server - Listeners page click Stop at the top right-hand side of the area that shows the details of the communications process you want to stop.
Note:
  • You can stop a communications process only if:
    • The enterprise server is started.
    • The status of the communications process is "Started".
  • When a communications process stops, all the service listeners it owns stop too.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To View Communications Processes and Listeners for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose listeners you want to view.
  3. If you can't see the listeners, choose All from the list of options in Listener Display Filters Process.
Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


To View Statistics for a Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server whose communications process you want to view statistics for. This server must have been started already.
  3. On the Edit Server - Listeners page click Statistics at the top right-hand side of the area that shows the details of the communications process.

    The Statistics are displayed in a new Web browser window.

Parent topic: Configuring Communications Processes
Parent topic: Work with Communication Processes and Service Listeners


Configuring Listener Conversation Types

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A listener's conversation type is shown in the Conversation Type column on the listener configuration page.

The available configuration settings for a listener are grouped its conversation type.

Some conversation types use TCP/IP protocol, and some use Legacy Micro Focus Application Format. The format that the conversation uses is shown on the Legacy Micro Focus Application Format checkbox on the Edit Listener page. With the Custom Format type, you can choose whether or not to use Legacy Micro Focus Application Format.

  • Web Services and J2EE conversation type
  • Web conversation type
  • Fileshare conversation type
Parent topic: Configuring Client-Server Communications


Web Services and J2EE conversation type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

There are no settings for this conversation type.

Parent topic: Configuring Listener Conversation Types


Web conversation type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

These options are checked for each request.

The [virtual paths] section is used to translate between the top-level path elements specified in URLs and the actual file-system directories they correspond to. For example, for the URL “http://host/path/to/file”, the [virtual paths] section will be consulted for an entry for “path”. Entries in this section are case-sensitive. For a more detailed explanation of the way these settings work, see the section Deployment Services and Listeners in the chapter Configuration.

The [allow] section is used to restrict what files the Web connector will serve out of a given directory.

[options]
logging=logging-level
[virtual paths]
<default>=default-directory
element=file-system-path
[allow]
element=list-of-filenames
  • logging
    Controls what information is logged.
  • default
    Specifies the directory to which unrecognized URL top-level path elements will be mapped.
  • element in [virtual paths] Section
    Specifies the file-system path to which element will be mapped.
  • element in [allow] Section
    Lists one or more filenames or wildcard pattern specifications, separated by spaces, which the connector is allowed to serve for files on this virtual path.
Parent topic: Configuring Listener Conversation Types
Related information
Deployment Services and Listeners


logging

Controls what information is logged.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

logging=logging-level

Parameters:

logging-level
Can be one of:
yes or 1 | Log various information while processing web requests, including path translation and CGI program execution
any other value | No logging

Properties:

Default: No logging
Parent topic: Web conversation type


default

Specifies the directory to which unrecognized URL top-level path elements will be mapped.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

default=default-directory

Properties:

Default: /dev/null

Comments:

The default directory must not exist, so that when the communications process translates the URL into a full path, the request will fail.

Parent topic: Web conversation type


element in [virtual paths] Section

Specifies the file-system path to which element will be mapped.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

 element=file-system-path

Parameters:

element The file-system path that element will be mapped to. element must be the top-level (first) element in the URL’s path. Some special tokens can be specified at the beginning of the value:
<ES>: | Replaced with the path to the base installation directory on Windows, or $COBDIR on UNIX
<ASEE>: | Historical synonym for ES.
<$name>: | Replaced with the contents of environment variable name
Parent topic: Web conversation type


element in [allow] Section

Lists one or more filenames or wildcard pattern specifications, separated by spaces, which the connector is allowed to serve for files on this virtual path.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

element=list-of-filenames

Parameters:

element | The file-system path that element will be mapped to.
list-of-filenames | Zero or more filenames or filename patterns, separated by spaces. Only files which match one of these filenames will be served. You can use the wildcards "?" (matches any one character) and "*" (matches zero or more characters).

Properties:

Default: Permit serving all files
Parent topic: Web conversation type


Fileshare conversation type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Fileshare connector checks these settings at the beginning of each conversation. Changes to them will take effect for subsequent conversations.

[Operation]
timeout=number-of-seconds
[Trace]
control=control-flow-trace
data=data-trace
file=pathname
  • timeout
    Sets the timeout, in seconds, for receiving data from the client.
  • control
    Enables the tracing of control flow in the connector.
  • data
    Enables the tracing of sent and received data.
  • file
    Specifies the full path of the file to receive trace messages.
Parent topic: Configuring Listener Conversation Types


timeout

Sets the timeout, in seconds, for receiving data from the client.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

timeout=number-of-seconds

Properties:

Default: Timeout for the communications process, which is 7200 seconds (two hours)
Parent topic: Fileshare conversation type


control

Enables the tracing of control flow in the connector.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

control=control-flow-trace

Parameters:

control-flow-trace Set to "yes" to trace various connector activities, such as passing a request to an enterprise server

Properties:

Default: Control flow tracing is disabled
Parent topic: Fileshare conversation type


data

Enables the tracing of sent and received data.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

data=data-trace

Parameters:

data-trace Set to "yes" to include data in the trace

Properties:

Default: Data tracing is disabled.
Parent topic: Fileshare conversation type


file

Specifies the full path of the file to receive trace messages.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

file=pathname

Properties:

Default: Trace messages are written to the MFCS log (as HTML)
Parent topic: Fileshare conversation type


Configuring Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section covers the tasks involved in creating and configuring service listeners.

  • To Add a Service Listener to an Enterprise Server Instance
  • To Edit a Listener
  • To Associate a Listener with a Service
  • To delete a listener
  • To Disassociate a Listener from a Service
  • To Start a Listener
  • To Stop a Listener
Parent topic: Configuring Client-Server Communications


To Add a Service Listener to an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server to which you want to add the listener.
  3. Click Add in the Listeners column for the communications process to which you want to add the listener.
  4. Specify a name for the service listener in Name.
  5. In Endpoint Address specify a host name or IP address to replace the first asterisk (*) and a port number to replace the second asterisk. You can leave the value as *:*, where the first asterisk (*) indicates the IP address of the current machine and the second indicates any available port number. Endpoint Protocol is always TCP.
  6. Choose an initial status from the list in Initial Status. Usually you should choose "Stopped".
  7. Click one button to choose a Supported Conversation Type for the listener:
    • Web Services / J2EE for client requests that use either of the conversation protocols supported by the Micro Focus request handlers, MFRHBINP and MFRHSOAP
    • Web for World Wide Web (HTTP) requests; Enterprise Server uses a Web listener for service deployment
    • Fileshare for Fileshare client requests
    • Custom can be used for any other type of requests. You can select whethr or not to use Legacy Micro Focus Application Format.
  8. If you clicked Custom in step 6, enter the name of the connector module for this type of request in the entry field next to Custom.
  9. Specify any configuration information the listener requires in Configuration Information.
  10. Specify a text description of the listener in Description (optional).
  11. Click Add.
Note: You can also reach the Add Listener page by clicking Edit to the left of the server to which you want to add the listener, clicking the Listeners tab and clicking Add.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Edit a Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server that owns the listener you want to edit.
  3. If you can't see the listener you want to edit, choose All from the list of options in Listener Display Filters Process.
  4. Click Edit to the left of the row containing the service listener that you want to edit.
  5. Update the attributes of the listener as required.
  6. Click OK.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Associate a Listener with a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details in the Objects column for the server that owns the service that you want to associate the listener with.
  2. Click Edit in the Operation column of the row containing the service that you want to associate the listener with.
  3. In Available Listeners click the service listener that you want to associate with the service.
  4. Click Add.

    The Directory Server associates the listener with the service immediately and redisplays the service table.

  5. If you want to associate another listener with this service, repeat steps 3 through 5.
Note: A service must always have at least one listener associated with it.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To delete a listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server that owns the listener you want to delete.
  3. If you can't see the listener you want to delete, choose All from the list of options in Listener Display Filters Process.
  4. Click Edit to the left of the row containing the service listener that you want to delete.
  5. Click Delete.
  6. Click Delete on the confirmation page.
Note:
  • You cannot delete a listener if it is the only listener for a communications process.
  • You cannot delete a service listener if it is associated with any service.
  • You cannot delete the deployment listener called Web that is created automatically when you create a new enterprise server.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Disassociate a Listener from a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details at the bottom of the Objects column.
  2. Click Edit in the Operation column for the row containing the service from which you want to disassociate the listener.
  3. In Associated Listeners click the service listener that you want to disassociate from the service.
  4. Click Remove.

    The Directory Server disassociates the listener from the service immediately and redisplays the service table.

  5. If you want to disassociate another listener from this service, repeat steps 3 through 5.
Note: A service must always have at least one listener associated with it.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Start a Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server that owns the listener you want to start.
  3. If you can't see the listener you want to start, choose All from the list of options in Listener Display Filters Process.
  4. Click Edit to the left of the row containing the service listener that you want to start.
  5. Click Started in New Status.
  6. Click OK.
Note: You can start a listener only if the server is started. When a server starts, any stopped listeners are started automatically.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


To Stop a Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Enterprise Server administration page is displayed in summary form, expand it by clicking expand button
  2. Click Details in the Communications Processes cell for the server that owns the listener you want to stop.
  3. If you can't see the listener you want to stop, choose All from the list of options in Listener Display Filters Process.
  4. Click Edit to the left of the row containing the service listener that you want to stop.
  5. Click Stopped in New Status.
  6. Click OK.
Note: You can stop a listener only if the server is started. When a server starts, any stopped listeners are started automatically.
Parent topic: Configuring Listeners
Parent topic: Work with Communication Processes and Service Listeners


Monitoring Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Server Instance Statuses
  • Monitoring the Directory Server
  • Collecting and Viewing Data on Transactions
Parent topic: Enterprise Server configuration and administration


Server Instance Statuses

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An enterprise server instance can have any of the following statuses:

Stopped | The server is currently not running.
Stopping | The server is currently in the process of terminating. This is normally a short-lived status value which should be shortly followed by a change to the value "Stopped".
Started | The server is currently running and can respond to client and server requests. At least one communications process is started.
Starting | The server is currently in the process of starting. This is normally a short-lived status value which should be shortly followed by a change to the value "Started".
Not Responding The server process was previously marked as "Started", but the server monitor has subsequently not been able to contact it. There may be some network connection error, or the server itself may have abnormally terminated without first marking itself as "Stopped".

If network communications are restored, and the server is still running, and the server monitor is on, then the server will be remarked as "Started" when the server monitor next checks whether the server is active.

The server might have encountered an unrecoverable communications error and the server process remains active, in which case you can shut it down by using Stop Server on the Server Details page.

The server might have encountered an unrecoverable communications error, that is, all the communications processes are inactive or not responding. If this happens, the server process shuts down. You can start it by using Start Server on the Server Details page.

Invalid | An error has occurred such that it has not been possible to set the status to any other value.

A CCI Server can only have the status Registered. This status indicates that the Directory Server has been notified that a CCI server has started. When the server stops, it deregisters itself and disappears from the list of servers.

Parent topic: Monitoring Enterprise Server


Monitoring the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes the facilities for monitoring the activities of the Directory Server.

  • Starting and Stopping the Directory Server
  • Displaying Server Information
  • Accessing Remote MF Directory Servers
  • Monitoring Facilities
Parent topic: Monitoring Enterprise Server


Starting and Stopping the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to access the Enterprise Server Administration user interface, the Directory Server must be running.

In a UNIX environment, depending on how Enterprise Server has been installed, either you can use the mfds command to start it, or it can start automatically when the machine is started.

To stop the Directory Server, you use a menu option on the Web interface.

To access the Directory Server using the Web interface, you start a Web browser and enter the address where the Directory Server is running.

Depending on how the Directory Server has been configured, and what you want to do, you might require a user ID and password. What you see and what you can do using Enterprise Server Administration depends on the security configuration settings and the permissions granted to your user account.

  • To Start the Directory Server from the Command Line
  • To Stop the Directory Server
  • To Delete the Repository
  • To Import a Repository
  • To Restore the Repository
  • To Export the Repository
Parent topic: Monitoring the Directory Server


To Start the Directory Server from the Command Line

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If you are running Directory Server on UNIX, log in as root.
  2. Enter:
    mfds /param

    where param can be:

    d | Show debug information
    j journal-path | Override the journal path
    k | Use SSL and specify SSL certificate, keyfile and password
    n network-address Bind to specific adapter.
    Note: You can use the CCITCP2_PORT environment variable to bind to a non-standard port, but this option should be used with caution, as many programs depend on Directory Server using the default port (86).
    o | Specify alternate MFDS options file
    r | Refuse access to the Enterprise Server Administration interface
    z | Override initial repository location
  3. In addition to options for starting Directory Server, the mfds command also provides a number of other options for reporting and exporting information, and stopping the server.
    c | Install as a service: show debug console
    e | Export MFDS user information to an LDIF file
    i | Install as a service: do not show debug console
    l | Export MFDS schema as an LDIF file
    m | Display current repository path
    s | Request controlled shutdown
    u | Remove as a service
    v | Show version information
    t | Convert journal file to text format
    x | Export repository data
    g | Import repository data
Note: The command to start the Directory Server can be inserted into your startup shell script; then the Directory Server will be started automatically when the machine is started. The mfds command must be inserted after the command to start up TCP/IP, because Directory Server needs TCP/IP to be running. If the command has been added to your startup shell script you would normally need to start the Directory Server only if you had shut it down since you started the machine. The startup script should also set up your environment. For more information see the section Starting Directory Server for the First Time in your Configuration and Administration Guide.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Start and Stop the Directory Server


To Stop the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: You can leave Directory Server running all the time, whether or not you are using Enterprise Server Administration. You should not shut down Directory Server if servers are started.

From the command line

Enter:
mfds -s
Parent topic: Starting and Stopping the Directory Server
Parent topic: Start and Stop the Directory Server


To Delete the Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

When you click Delete, all information in the current repository is deleted. If you have currently active clients and services, this will cause client application connection errors and loss of data.

  1. Click Delete All under Actions on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. If you are sure you want to delete the repository, click OK. Otherwise click Cancel.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Work with the Directory Server Repository


To Import a Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Import under Actions on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Specify the location of the repository that you want to import in Source directory containing server data to restore. By default, this is $COBDIR/etc/mfds.

    A list of recently used locations is supplied. Choosing an item from this list and clicking Select puts the value into Source directory containing server data to restore.

  3. Click Next and follow the screen prompts.
Note: When you import, you have the option of excluding any server that has the same name as one already present in the repository. Where the export contains security information, you also have the option of including or excluding it. See the context help for details.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Work with the Directory Server Repository


To Restore the Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Restore under Actions on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Specify the location from which you want the repository to be restored in Source directory containing server data to restore. This defaults to $COBDIR/etc/mfds.
  3. Choose whether you want to set the status of all restored servers to "Stopped", or to whatever they were when the servers were last saved, by clicking one of the radio buttons under When restoring servers.
  4. Check restore even if source repository is a duplicate, in part or whole, of the current one if you want server data to be restored even if all the server names in the backup repository are duplicates of server names in the current repository.
  5. Click OK.
Note: You can go back to the repository as it was when Enterprise Server was originally installed, by restoring from the \ivp subdirectory of $COBDIR/etc/mfds.
Warning: If you want to keep the information currently in the repository make sure you have saved it before you restore. When you restore the repository all the information in the repository is overwritten with the restored data. This might cause application connection errors and loss of data.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Work with the Directory Server Repository


To Export the Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Export under Actions on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Specify the location where you want to save the repository in Export information to this directory. This defaults to $COBDIR/etc/mfds.
  3. Choose the export option that you require and click OK.
    Note: If the target directory contains previously exported information, you will be presented with a confirmation page. This page will show the contents of the target directory. Proceeding with the export will overwrite previously exported details.
Note:
  • We recommend that you export the repository only when all the registered servers have a status of "Stopped".
  • When exporting to a file system location, if you specify a directory that does not exist, it will be created if the directory containing it exists, otherwise it will not be created and the export will fail.
  • Export enables you to export either: server definitions only, Security Manager definitions only, or server definitions and all related security configuration information.
Parent topic: Starting and Stopping the Directory Server
Parent topic: Work with the Directory Server Repository


Accessing Remote MF Directory Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Providing you have sufficient authorization, you can log on to remote MF Directory Servers and administer the installations they maintain. You can display all directory servers accessible from your network that are listening on port 86.

  • To View and Use Remote Directory Server Instances
Parent topic: Monitoring the Directory Server


To View and Use Remote Directory Server Instances

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Directories on the menu on the left-hand side of the Enterprise Server Administration Web page.

    Enterprise Server searches the network for all MF Directory Servers that use port 86, and displays a list of the MF Directory Servers that it finds.

  2. Click the right-pointing arrow in the DNS Resolved Hostname column for the remote machine that you want to view.

    A new browser window opens at the home page of Enterprise Server Adminstration for the instance of Directory Server running on the other machine.

Parent topic: Accessing Remote MF Directory Servers
Parent topic: Monitor Directory Server


Monitoring Facilities

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server Administration provides four facilities for monitoring the activities of the Directory Server:

  • The Directories Page
  • Viewing a MF Directory Server's Statistics
  • Viewing a MF Directory Server's Sessions List
  • Viewing the Journal
Parent topic: Monitoring the Directory Server


The Directories Page

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Directories page displays a table of all the other instances of Directory Server that are running on the local network and that are using the default Directory Server port (86). For each instance, it shows:

  • The version number of Directory Server
  • The IP address of the machine on which it is running
  • The DNS-resolved hostname of the machine on which it is running. Next to the hostname is a right-pointing arrow, which you can click to open a new Enterprise Server Administration window on your machine, giving you access to the other Directory Server and its objects without having to remember its IP address.
Note: You should take care to ensure that an appropriate level of security has been set up for all the instances of Directory Server on a local network, to reduce the possibility of unauthorised access using the Directories page. For more on security and the options available, see Introduction to COBOL Server Security.
Parent topic: Monitoring Facilities
Related information
Introduction to Enterprise Server Security


Viewing a MF Directory Server's Statistics

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Statistics page displays statistics and other information about the Directory Server and the current activity on it. The information is of four types:

  • Repository location and status
  • Objects in the repository, subdivided into servers, listeners, services, request handlers and packages, with a total. The services number actually represents the number of service operations
  • Request processing statistics
  • Configuration options settings
  • File paths used by the Directory Server

You might find the information on this page helpful if you are experiencing problems, for example, if you deployed a service, but you cannot find it in the Services table, you can check whether the numbers of services and packages have changed.

  • To View Directory Server Statistics
Parent topic: Monitoring Facilities


To View Directory Server Statistics

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Click Statistics on the menu on the left-hand side of any Enterprise Server Administration Web page.
Parent topic: Viewing a MF Directory Server's Statistics
Parent topic: Monitor Directory Server


Viewing a MF Directory Server's Sessions List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Sessions list is a list of all the Web browser client and program clients currently connected to the MF Directory Server. The sessions may be active, or they may be dormant but not yet removed because the time period between inactivity and removal has not yet been exceeded.

If user access is unrestricted (that is, if security has not been configured for Directory Server), only one Web browser client session is shown, with the Session ID "Developer".

If user access is restricted, individual sessions are shown for each Web browser client session user, identifed by unique user IDs.

  • To View the Sessions List
Parent topic: Monitoring Facilities


To View the Sessions List

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Click Sessions on the menu on the left-hand side of any Enterprise Server Administration Web page.
Parent topic: Viewing a MF Directory Server's Sessions List
Parent topic: Monitor Directory Server


Viewing the Journal

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Journal is a file that records some of the activity occurring on the MF Directory Server. It can track usage and help with support issues.

You can choose one of three levels of journaling:

  • Errors only (default)
  • Errors and warnings
  • All information. With this level there is a performance degradation. The scale of the degradation depends on many factors such as file system performance and client traffic; a system with a large number of highly active program clients suffers the most

You set the journaling level using the Configure Options page.

  • To View the Journal
  • To export the journal as a text file
  • To Delete Journal Entries
Parent topic: Monitoring Facilities


To View the Journal

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Click Journal on the menu on the left-hand side of any Enterprise Server Administration Web page.
Parent topic: Viewing the Journal
Parent topic: Directory Server Journal
Parent topic: Monitor Directory Server


To export the journal as a text file

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Journal on the menu on the left-hand side of any Enterprise Server Administration Web page.
  2. Click Export as Text. The text file journal.txt will be created in the directory /var/mfcobol/logs . If the file already exists it will be overwritten.
Parent topic: Viewing the Journal
Parent topic: Monitor Directory Server


To Delete Journal Entries

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Journal on the menu on the left-hand side of any Enterprise Server Administration Web page.
  2. Click Delete. A new journal is started.
Parent topic: Viewing the Journal
Parent topic: Monitor Directory Server


Collecting and Viewing Data on Transactions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can create records for tasks that have been executed and completed under Enterprise Server using the Historical Statistics Facility (HSF). These records can be written to a .csv file and also a limited number can be saved in memory to view in the Enterprise Server Monitoring and Control console (ESMAC).

The records contain information such as the ID of a user that initiates the task, the response time, and names of any files accessed.

Information is provided for the following resources:

  • Web services
  • Configuring and Starting Transaction Data Collection
  • Viewing HSF Information in ESMAC
  • Viewing HSF Information as a .csv File
  • Analyzing Aggregated HSF Data in .csv Files
Parent topic: Monitoring Enterprise Server


Configuring and Starting Transaction Data Collection

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To use HSF to collect data about transactions, you need to set a number of configuration options in Enterprise Server Administration. You can also use ESMAC to override these settings dynamically.

Note: In order to collect information on EXEC SQL statements, you need to compile the application with the HSFTRACE directive set.

To configure HSF

  1. Access the Enterprise Server Administration screen for your installation.
  2. Check that the server you want has stopped, and if not, stop it.
  3. In the Status column of the Enterprise Server to monitor, click Details.
  4. Select the Historical Statistics tab.
  5. Set the configuration options:
    Enable collection of Historical Statistics Facility (HSF) records
    This switches on HSF processing.
    Write to disk
    Enables writing of HSF records to comma-separated files. These are called cashsf-a.csv and cashsf-b.csv, and are written to the system directory. Only one file is written to at any one time - this is called the active file.

    You write to the active file until you click the ESMAC Switch button or when the active file reaches the maximum size, at which point the alternate file becomes active. If the alternate file already exists it will be backed up with the name cashsf.nnn where nnn is the number of the backup. When you start an enterprise server, cashsf-a.csv is always set as the active file, and if it already exists it is backed up.

    Backup extensions are numbered from .001 up to .999. When a backup with extension .999 exists then the next backup will be created as cashsf.001. If cashsf.001 already exists then it will be overwritten.

    Maximum HSF file size (KB)
    If you have selected Write to disk, this is the size in kilobytes the .csv file will reach before Enterprise Server switches to the alternate .csv file. A value 0 selects the maximum size possible (4 Gb).
    Number of records displayed by ES Monitor & Control
    The number of HSF records that Enterprise Server will hold in memory. These records can be viewed by clicking on the HSF button in ESMAC while the server is running. When this number is reached, older records will be deleted when a new one is created. Records older than one hour are deleted too.
    The minimum value is 0 (no HSF data displays in ESMAC), the maximum is 4096.

To reconfigure HSF while a server is running

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the Status column of the started Enterprise Server, click Details.
  3. Select the Server > Control tab and click ES Monitor & Control, then click Control.
  4. Set the configuration options. These are the same as those in the Enterprise Server Administration Historical Statistics tab described above apart from the following differences:
    Enable collection of HSF records
    To enable this option you must first either set Write to disk or enter a value in the Number of records to view field.
    Switch
    Clicking this button will switch collection to the alternate .csv file before the active file has reached the maximum size.
  5. Click Apply to start collecting the data.
Parent topic: Collecting and Viewing Data on Transactions
Related information
To start an enterprise server instance


Viewing HSF Information in ESMAC

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have enabled collection of HSF records and specified the number of records to collect in ESMAC, you can use ESMAC to view aggregated information on transactions, and details of individual runs of those transactions.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To view the transaction information:

  1. Click the HSF button.

This shows the period of time (displayed in minutes and seconds next to Historical Statistics) between the earliest records displayed and the current time. Records older than one hour are deleted. The following information is shown for each transaction:

Average Latency
The average time, in hundredths of a second, between Enterprise Server receiving the requests and the tasks beginning to run.
Average Response Time
The average time, in hundredths of a second, that the tasks ran for (not including latency time).
Count
How many times the task has run.

By clicking on the magnifying glass icon [image] next to a task you get a detailed view of the individual runs.

Latency+Resp
The sum of latency and response time averages.
Transaction
The name of task:
  • for Web services, the service name
Process ID
Process ID of the SEP which ran the task.
Task Number
A unique task number.
Date
The date the task started to run, in the format yyyymmdd.
Time
The time the task started to run, in the format hhmmsscc.
Parent topic: Collecting and Viewing Data on Transactions
Related information
To start an enterprise server instance


Viewing HSF Information as a .csv File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have enabled the collection and writing of HSF records to disk, you can view details of individual runs of transactions in comma-separated files that you can import into a spreadsheet. These files contain one HSF record per line. The filenames are cashsf-a.csv and cashsf-b.csv.

Once the active file is full, or when you click the Switch button in ESMAC, records are then written to the alternate file until the maximum file size is reached or the Switch button is clicked.

The files are saved in the system directory.

The .csv files have the header:
#HSFver=02
Type,PID,Task,Date,Time,Tran/Job,User/DDName/CC,LU/Step,Prog/DSName,Latent/ReadCount,Resp/WriteCount,
API/RewriteCount,SQL/DeleteCount,IMS/DSDeleteCount,DSType,DSAccessType,File1,Count1,Time1,File2,Count2,
Time2,File3,Count3,Time3,File4,Count4,Time4,File5,Count5,Time5,TS1,Count1,Time1,TS2,Count2,Time2,TS3,
Count3,Time3,TS4,Count4,Time4,TS5,Count5,Time5,TD1,Count1,Time1,TD2,Count2,Time2,TD3,Count3,Time3,TD4,
Count4,Time4,TD5,Count5,Time5
and contain the following fields.
Important:
This version of the product generates cashsf-n.csv files that start with the line:
#HSFVer=02
HSF output from earlier versions of the product may either not have this line at all, or start with:
#HSFVer=01
Earlier .csv files do not have the DSType and DSAccessType fields, and either have this header:
#HSFVer=01
Type,PID,Task,Date,Time,Tran,User,LU,Prog,Latent,Resp,API,SQL,IMS,File1,Count1,Time1,File2,Count2,Time2,
File3,Count3,Time3,File4,Count4,Time4,File5,Count5,Time5,TS1,Count1,Time1,TS2,Count2,Time2,TS3,Count3,
Time3,TS4,Count4,Time4,TS5,Count5,Time5

or, without the IMS field:

Type,PID,Task,Date,Time,Tran,User,LU,Prog,Latent,Resp,API,SQL,File1,Count1,Time1,File2,Count2,
Time2,File3,Count3,Time3,File4,Count4,Time4,File5,Count5,Time5,TS1,Count1,Time1,TS2,Count2,Time2,TS3,
Count3,Time3,TS4,Count4,Time4,TS5,Count5,Time5
Type
The type of record. One of:
  • WEB - for Web services
PID
Process ID of the SEP which ran the task.
Task
A unique task number.
Date
The date the task started to run, in the format yyyymmdd.
Time
The time the task started to run, in the format hhmmsscc.
Tran/Job
The name of task:
  • For Web services, the service name.
Latent/ReadCount
  • The time, in hundredths of a second, between Enterprise Server receiving the request and the task beginning to run.
Resp/WriteCount
  • The time, in hundredths of a second, that the task ran for (not including latency time).
SQL/DeleteCount
  • The time spent, in hundredths of a second, in SQL API (EXEC SQL statements) for this task.
DSType
This field is blank for all records
DSAccessType
This field is blank for all records

The following additional fields may be repeated up to five times:

File(x)
The name of a file that the transaction accessed.
Count(x)
The number of times the transaction accessed this filex.
Time(x)
The time, in hundredths of a second, the transaction spent accessing filex.
Ts(x)
The name of a temporary storage queue (TSQ) that the transaction accessed.
Count(x)
The number of times the transaction accessed Ts x.
Time(x)
The time, in hundredths of a second, the transaction spent accessing Ts x.
Count(x)
The number of times the transaction accessed TD x.
Time(x)
The time, in hundredths of a second, the transaction spent accessing TD x.

Sample content viewed in Microsoft Excel

Parent topic: Collecting and Viewing Data on Transactions


Analyzing Aggregated HSF Data in .csv Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use the statistics utility program, casfhsf, to output aggregated data from the .csv files created by the Historical Statistics Facility (HSF). casfhsf outputs this data as a comma-separated value file.

You can use the information to review system performance on a regular basis and avoid going through a large volume of data in order to determine if corrective tuning action is required.

Note: The .csv files do not have to be generated on the same platform as the one on which you run casfhsf.

Using the casfhsf statistics utility program

From the Visual COBOL command prompt, launch casfhsf32 or casfhsf64, depending on your environment.

The following switches are available. A dash may replace the slash, and switches can be upper or lower case.

Switch | Description
/A | Process only cashsf-a.csv.
/B | Process only cashsf-b.csv.
/C | Process both cashsf-a.csv and cashsf-b.csv (default).
/D | Process only backup files cashsf.nnn.
/E | Process all files: cashsf-a.csv, cashsf-b.csv, and cashsf.nnn.
/S{sd,st,ed,et} | Aggregate the output data by the second. Where {sd,st,ed,et} = yyyymmdd, hhmmss, yyyymmdd, hhmmss - start date, start time, end date, end time.
/M{sd,st,ed,et} | Aggregate the output data by the minute (default if error). Where {sd,st,ed,et} = yyyymmdd, hhmm, yyyymmdd, hhmm - start date, start time, end date, end time.
/IP | The location of the input files. The default value is the current directory.
/OP | The location of the path of the output file. The default value is the current directory. The output file is called OutFile.csv.

To aggregate certain transactions or programs, you may specify these using parameters in the form:

{type},{id}[[,{type},{id}]...]
The parameters are:
type
Transaction type:
  • WEB = a Web Service
id
The identifier of the service or program ID to be aggregated.

You can specify between zero and five type,id pairs. Each type must be separated from its corresponding id by a comma. If more than one pair is specified, each pair must be separated by a comma.

If no pair is specified, an aggregate of all transactions is accumulated in the first unallocated slot. The default behavior in this case is to aggregate all data in slot one.

An extfh.cfg file is generated in the current directory, if one is not already present, to allow large file inputs.

If no switches or parameters are specified, the utility will ask if you wish to continue using the default values.

Example
casfhsf32 /op"/opt/Micro Focus/logs"
Using the input defaults, this processes both cashsf-a.csv and cashsf-b.csv in the current directory, aggregates times (in minutes) for all transactions and programs, and creates the output file in the folder /opt/Micro Focus/logs.

The Output File

This is a comma-separated value file with the following header:
time,TPS,Latency,min,max,Response,min,max,System,min,max,API,min,max,SQL,min,max,IMS,min,max...
After the time field, the rest of the fields occur five times.
Field | Description
time | The time period in minutes (hh:mm format) or seconds (hh:mm:ss format) into which the input monitoring times are aggregated. The format is determined by the /S or /M switch.
TPS | The average number of transactions per second or minute.
Latency,min,max | The average latency - delay or waiting time - for this time period, and the minimum and maximum latency.
Response,min,max | The average time taken for Enterprise Server to respond to the transaction request, and the minimum and maximum response times.
System,min,max | The total of the average latency and response times (Latency + Response) , and the minimum and maximum totals of latency plus response time of a particular transaction run.
SQL,min,max | The average time, in hundredths of a second, spent in SQL API (EXEC SQL statements) for this task, and the minimum and maximum times.

There is also a secondary header depending on the parameters supplied to the utility.

If there are no parameters, then all the aggregate values are accumulated under "Everything", and the other four columns are marked as "Unused".

Versions of input files

This version of the product generates cashsf-n.csv files that start with the line:
#HSFVer=02
HSF output from earlier versions of the product may either not have this line at all, or start with:
#HSFVer=01

If you are processing multiple files, casfhsf will only aggregate data from files of the same version as the first file it receives. Other versions are ignored. However, whatever version it processes, the output file OutFile.csv will contain all the fields listed above, with values of zero for any missing fields.

Parent topic: Collecting and Viewing Data on Transactions


User Exits for Request Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes how to write user exit programs that allow you to customize the behavior of the Micro Focus MFRHSOAP request handler.

The Micro Focus MFRHSOAP request handler provides a number of user exit points, enabling you to supply a user exit program that can perform additional processing of input and output parameters.

You can also provide a user exit program for use with a custom request handler, if you find this approach offers advantages over including all the code you need in the request handler itself.

  • User Exit Points Provided
  • Structure Definitions and Type Definitions
  • Linkage Section Field Names
  • Deploying a User Exit Program
Parent topic: Enterprise Server configuration and administration


User Exit Points Provided

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following diagram shows the interaction between request handlers, the application container and the run-time interface mapper.

Figure 1. Request Handler Exit Points
Request Handler Exit Points
The user exit points are indicated by squares numbered from 1 through 9. The table below gives the name and purpose of the exit points.
Number | Name | Description
1 | External data value modification – input parameter | Enables you to modify the external data value specified in a client request before the request handler’s default mapping for the parameter occurs. This exit point is invoked for each external-to-internal input parameter mapping that is specified in the IDT.
2 | Internal data value modification – input parameter | Enables you to override the internal data value created by the request handler’s default mapping for a parameter. This exit point is invoked for each external-to-internal input parameter mapping that is specified in the IDT.
3 | Unmapped named external input parameter | Enables you to provide processing of any input parameters that do not have associated input parameter mappings defined in the IDT. This exit point is invoked for each unmapped named input parameter.
4 | End of input request processing | Enables you to set up parameter values other than the external parameters specified in the client request. It also provides the opportunity for any resources allocated in exit points 1 through 3 to be released.
5 | Start of response processing | Enables you to bypass completely the default mapping used to build a client response. The exit program is responsible for the creation of the response that will be sent back to the client by the application container.
6 | Internal data value modification – output parameter | Enables you to modify the internal data value as created by the user application before the request handler’s default mapping for the parameter occurs. This exit point is invoked for each internal-to-external output parameter mapping that is specified in the IDT.
7 | External data value modification – output parameter | Enables you to override the external data value created by the request handler’s default mapping for a parameter. This exit point is invoked for each internal-to-external output parameter mapping that is specified in the IDT.
8 | End of response processing | Enables you to modify the response generated by the default mapping.
9 | End of request processing | Enables you to release any resources that were allocated in exit points 1 through 8.
Parent topic: User Exits for Request Handlers


Structure Definitions and Type Definitions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To help COBOL and C programmers, we provide a COBOL copybook (cbltypes.cpy) and a C header file (svext.h) with COBOL Server. These files contain definitions of the structures and interfaces that you will require to write user exits and custom request handlers.

One of these is the IDP_EXIT_INFO structure, which is used for passing the information required by the exit routines for processing at each exit point. A pointer to this structure, together with the exit point identifier, is passed to each exit routine. The information passed and returned depends on the exit point.

For definitions of the information passed at each exit point see the reference Help topics Exit Points.

For definitions of support functions see the reference Help topics Functions.

Parent topic: User Exits for Request Handlers
Related information
Exit Interface Definition
External Data Value Modification - Input Parameter (Exit Point 1)
Internal Data Value Modification - Input Parameter (Exit Point 2)
Unmapped Named External Input Parameter (Exit Point 3)
End of Input Request Processing (Exit Point 4)
Start of Response Processing (Exit Point 5)
Internal Data Value Modification - Output Parameter (Exit Point 6)
External Data Value Modification - Output Parameter (Exit Point 7)
End of Response Processing (Exit Point 8)
End of Request Processing (Exit Point 9)
PFV_IDPES_FN_ALLOC_MEM
PFV_IDPES_FN_FREE_MEM
PFI
PFI_IDPES_FN_DISPLAY_TO_UTF16
PFI_IDPES_FN_UTF16_TO_DISPLAY
IDP_EXIT_INFO
IDP_EXIT_SERVICE_FUNCS


Linkage Section Field Names

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Several of the exit points are provided so that you can manipulate an input or output field. The way you pass a field name in the exit interface depends on how it is defined in the Linkage Section of the program providing the service. There are two possibilities:

  • The item is defined at level 01. In this case, the field name passed in the exit interface is the same as the field name in the Linkage Section
  • The item is defined at a level subordinate to level 01. In this case, the field name passed in the exit interface is composed of the field name prefixed by a concatenation of the names of the group items that it belongs to. The individual names are separated by "." characters. For example: field "e" in the record below would be uniquely identified as "a.b.c.e".
    01 a.
   03 b.
      05 c.
         07 d     pic x(4).
         07 e     pic x(4).
         07 f     pic x(4).
      05 g        pic x(4).
   03 h           pic x(4).

    If the field itself, or any of the group items that it belongs to, are tables, the required table index is specified by appending “(n)” to the name, where n indicates the position of the field or item in the table. For example, field “f” of the fourth element of “c” in the record below would be uniquely identified as “a.b.c(4).f”:

    01 a.
   03 b.
      05 c occurs 10.
         07 d     pic x(4).
         07 e     pic x(4).
         07 f     pic x(4).
      05 g        pic x(4).
   03 h           pic x(4).
Parent topic: User Exits for Request Handlers


Deploying a User Exit Program

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To deploy a user exit program compiled to callable shared object format, copy it into a directory that is on $LD_LIBRARY_PATH ($LIBPATH on AIX systems, $SHLIB_PATH on HP PA-RISC systems).

Parent topic: User Exits for Request Handlers


Troubleshooting

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes how to set about diagnosing common problems that can occur with running applications in Enterprise Server and gives some advice about overcoming them.

Failures fall into the following categories:

  • Incorrect output (an application or system function produces the wrong results or exhibits unexpected behaviors). These include application abends.
  • Unexpected system terminations. Either the whole enterprise server terminates or a subsystem (support process) terminates.
  • System loops. These include application loops and enterprise server subsystem loops. They are characterized by an abnormal accumulation of CPU time by an enterprise server process and may display the same external symptoms as a system hang.
  • System hangs. Any problem where the enterprise server appears to stop responding to its clients (except for loops).

    This can also be the result of problems with inter-system communications.

  • Determining the Failure Type
  • Collecting Information
  • Data Capture
  • Checking the Communications Process
  • Using a Diagnostics Server
  • What You Can Do with Dumps and Traces
  • Problems Caused by Process Limits
Parent topic: Enterprise Server configuration and administration


Determining the Failure Type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Key initial classifiers for a failure are:

  • The console log.

    This contains an easy-to-read history of enterprise server system activity leading up to the problem. When viewing the console log:

    • Investigate messages with levels other than information first.
    • Frequently, the enterprise server will continue to appear normal for some time after a failure so the 10 to 15 minutes before the failure should be investigated in detail (including the information messages).
  • The list of processes.

    Inspect the processes associated with the failing enterprise server (providing the server did not shut down). Loops may be indicated if there is a significant difference in the CPU time for a process between the list in the healthy data capture and the list in the problem data capture.

  • The list of shared memory areas and semaphores.

    An unusual number of objects may indicate an operating system problem. To evaluate this, compare the list with one obtained when the enterprise server system is in a healthy state.

These classifiers coupled with the external symptoms should provide enough information to assign the failure to one of the types of failure listed.

  • Incorrect Output
  • Unexpected System Termination
  • Invalid Credentials Error
Parent topic: Troubleshooting


Incorrect Output

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The next step here is to differentiate between application problems and enterprise server infrastructure problems.

Application failures other than abends are often application problems. Look at the active trace dataset coupled with the system trace table in the dump X dataset (casdumpx.rec) to establish the application activity before the failure.

Application abends can be due to application problems or enterprise server infrastructure problems. Look in the active dump dataset for an RTS error dump. If found, evaluate the RTS error and classify the problem from this. What module experienced the failure, application or enterprise server infrastructure?

Parent topic: Determining the Failure Type


Unexpected System Termination

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Inspect the system console log for messages indicating the cause of the shutdown and classify the failure from these.

  • Loops
  • System Hangs
Parent topic: Determining the Failure Type


Loops

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use the name of the looping process to classify the failure. If the looping process is a service execution process (SEP), the loop could either be in an enterprise server subsystem or in the application; look at the active trace dataset and the system trace table from the dump X dataset to determine which module last got control.

If the looping process is not a SEP, or the last module to get control was not part of the application, you should refer the problem to Micro Focus technical support.

Parent topic: Unexpected System Termination


System Hangs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Find out whether all client requests are suffering from lack of response from the enterprise server, or just one type of request.

Try dynamically increasing the number of service execution processes by clicking Details in the Current status column, then on the Enterprise Server Details page, specifying the new number in Requested Service Execution Processes and clicking Update. The new processes should appear in the list after a short delay. Success shows that shared memory is not locked and that the enterprise server is still functioning correctly at some level, even though the external symptoms of the problem might still be present.

Check the number of active service execution processes (SEPs), using the dump X dataset. Inspect the despatch control blocks, one for each service execution process. Are all service execution processes currently occupied with a transaction? Is the occupying transaction the same for each process or was the last command executed by each process the same? If either of these is true, consider the following possibilities:

  • That enough requests of the problem type have arrived to block all the available processes, such that it appears that the whole enterprise server has failed. This might indicate a customer application issue.
  • That enough normal long running requests have arrived to occupy all available processes, such that it appears that the whole enterprise server has failed. If this seems likely, you might be able to fix the problem by increasing the number of service execution processes.

Another possibility is that the server's shared memory is locked. The best way to check for this is to compare the date and time of the last trace entry in the dump X dataset to the date and time of the dump. The larger the gap between the two times, the more likely it is that shared memory is locked. If shared memory is not locked, try to determine what the server is waiting for. If shared memory is locked, try to determine which process left shared memory in this condition.

Another possibility is that rather than the failure being the result of some problem with the application or the enterprise server, it is instead the result of the enterprise server running up against the operating system's process limits. This is discussed at length in the section Process Limits.

  • One Type Of Request is Failing
  • All client requests are failing
Parent topic: Unexpected System Termination


One Type Of Request is Failing

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Consider the possibility that the application is suffering the effects of resource contention. Consider the possibility that the service listener has failed.

Parent topic: System Hangs


All client requests are failing

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Try dynamically increasing the number of service execution processes by clicking Details in the Current status column, then on the Enterprise Server Details page, specifying the new number in Requested Service Execution Processes and clicking Update. The new processes should appear in the list after a short delay. Success shows that shared memory is not locked and that the enterprise server instance is still functioning correctly at some level, even though the external symptoms of the problem might still be present.

Check the number of active service execution processes (SEPs) using the dump X dataset. Inspect the despatch control blocks, one for each service execution process. Are all SEPs currently occupied with a transaction? Is the occupying transaction the same for each SEP or was the last command executed by each process the same? If either of these is true, consider the following possibilities:

  • That enough requests of the problem type have arrived to block all the available processes, such that it appears that the whole enterprise server instance has failed. This might indicate a customer application issue.

  • That enough normal long running requests have arrived to occupy all available processes, such that it appears that the whole enterprise server instance has failed. If this seems likely, you might be able to fix the problem by increasing the number of service execution processes.

Another possibility is that the enterprise server instance's shared memory is locked. The best way to check for this is to compare the date and time of the last trace entry in the dump X dataset to the date and time of the dump. The larger the gap between the two times, the more likely it is that shared memory is locked. If shared memory is not locked, try to determine what the enterprise server instance is waiting for. If shared memory is locked, try to determine which process left shared memory in this condition.

Parent topic: System Hangs


Invalid Credentials Error

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you get an INVALID_CREDENTIALS error in the console log when an enterprise server starts up, as follows:

CASCD4002W Error (INVALID_CREDENTIALS) binding to MFDS CASCD0102F TX Daemon Failed to Initialize

this indicates a problem with the internal files that hold details of Directory Server user IDs and passwords (in encrypted form). If you see this error, you should check that the following files exist in the Micro Focus Directory Server schema directory, which by default is $COBDIR/etc/mfds:

  • usr.dat

  • ugp.dat

  • ace.dat

  • prm.dat

These files are initially created from the cciusers.dat file located in $COBDIR/etc. If there was a problem reading this file or creating the initial security information, you can attempt to recreate the data by re-importing this file. To do this:

  1. On the home page of Enterprise Server Administration, click Users in the menu on the left hand side.

  2. Click Import... under the list of users.

    This displays a page confirming the location of the cciusers.dat file, and asking whether you wish to replace all existing user information (default: yes).
    Note: Import... is not available when your Directory Server is running in restricted mode.

  3. Click OK.

To start an enterprise server requires that certain system user accounts exist. The user IDs required are mf_mdsa and mf_cs, and they should exist in the default cciusers.dat file which is shipped with the product.

Parent topic: Determining the Failure Type


Collecting Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For all troubleshooting exercises it is essential to gather as much information as possible about the state of the enterprise server when the problem occurred and about the events leading up to the problem.

When a problem occurs, you need to capture not only the current log files, dumps and traces, but also the contents of various files, directories and areas, and the output from a number of operating system tools. It is important to have data capture mechanisms in place in advance of a failure so that the data can easily be obtained when required.

In a production system, we recommend that you restore the enterprise server service to its clients before you start analyzing the data you have captured. We also recommend that you perform data capture on the enterprise server in a healthy state shortly after the supporting operating system has been rebooted and the enterprise server started. You should retain this healthy data capture to compare with the failure data capture.

You should also check whether the enterprise server is responding to client requests, and to requests from ESMAC. Lack of response points to problems with the communications process (MFCS).

  • Directory Server Journal
  • Enterprise Server Log Files
  • Enterprise Server System Directory
  • Dumps and Traces
Parent topic: Troubleshooting


Directory Server Journal

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can change the maximum file size, the number of entries displayed and the level of logging on the Configure Options page of Enterprise Server Administration. When the journal reaches the maximum file size set, the most recent journal entries overwrite the oldest journal entries. For troubleshooting purposes, you might want to increase the maximum file size to 256 KB or more.

The three levels of logging available are:

  • Errors only
  • Errors and warnings
  • All information

For troubleshooting purposes, you might want to set the maximum level of logging.

  • To View the Journal
Parent topic: Collecting Information
Related information
To configure the Directory Server
To view the journal


Enterprise Server Log Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For each enterprise server instance, you can view the following log files to help identify the cause of any problems:

  • The server console log (ES Console on the ESMAC tab menu) provides information about the server instance. This includes such details as when the server was started or stopped, the SEPs that were created, and so on.
  • The communications process log (CS Console on the ESMAC tab menu) provides information on the communications processes.
  • Communications Process Log Files
  • Enterprise Server Log Files
  • To View the Enterprise Server Log Files
Parent topic: Collecting Information


Communications Process Log Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Communications processes (MFCS) log messages to the communications process log file, log.html, in its System Directory.

If multiple communications processes are running, the date and time stamp at the beginning of each message is followed by an instance identifier in square brackets, for example, [2].

By default, there is only one log file which grows continuously until it is deleted by an administrator. However, you can use the mf-server.dat file to activate rotating log files, and to change the level of logging. The mf-server.dat file is located in $COBDIR/etc . It uses the ini-file format of section tags in square brackets followed by name=value pairs.

With rotating log files, MFCS uses multiple log files, named log-1.html, log-2.html, etc. When a log file reaches a configured size, MFCS moves on to the next file (which will be deleted first if it already exists). When it reaches the configured number of log files, it returns to log-1.html, overwriting it.

The syntax is as follows:

[logging]
 files=number-of-files
 filesize=maxsize
 dscontrol=none|standard|all
 dirsvc=none|unusual|processing|not-found|all

All the parameters are optional. However, to activate rotating log files, both files= and filesize= must be set, and files= must be set to a number greater than 1. These parameters configure rotating log files, as explained above. If both are set, then the total log file space required by MFCS will not exceed files*filesize (approximately). For example, to limit the log to three files of 100 KB each:

[logging]
files=3
filesize=100

The parameters are explained below.

  • Files
  • filesize
  • dscontrol
  • dirsvc
Parent topic: Enterprise Server Log Files
Related information
System Directory


Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.
files=number-of-files
Specifies the number of log files.
Parent topic: Communications Process Log Files


filesize

Restriction: This topic applies only when the Enterprise Server feature is enabled.
filesize=maxsize
Specifies the maximum size of a log file in kilobytes (KB)
Parent topic: Communications Process Log Files


dscontrol

Restriction: This topic applies only when the Enterprise Server feature is enabled.
dscontrol=none|standard|all

Sets the level of logging for control messages. These messages normally come from Directory Server (MFDS) though they can come from other sources as well. These messages include server monitor probes, requests for log and dump data, and dynamic configuration changes.

none
Don't log control messages.
standard
Log control messages that update MFCS configuration or status. Don't log messages that just request information, such as the KEEPALIVE probe messages that MFDS uses to check if the enterprise server is still running.
all
Log all control messages.

You might want to set this to "all" if you are investigating a problem with the server monitor or other control flows, or set it to "none" if you want to avoid logging messages about configuration changes or other control requests.

Default = standard

Parent topic: Communications Process Log Files


dirsvc

Restriction: This topic applies only when the Enterprise Server feature is enabled.
dirsvc=none|unusual|processing|not-found|all
none

Don't log information about Directory Server activities.

unusual
Only log unusual results, such as duplicate object names, which may indicate configuration problems.
processing
Also log some messages about the progress of normal processing. This is the default.
not-found
Also log some messages about searches that return a not-found status. Normally these are not logged because MFCS expects some optional configuration items to be missing if they are not needed. In some cases, though, logging all not-found results may help diagnose configuration issues.
all

Log even more information, including normal MLDAP unbind operations.

Default: processing

Parent topic: Communications Process Log Files


Enterprise Server Log Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An enterprise server logs messages to a file, console.log, in its System Directory.

When an enterprise server starts, it renames any existing console.log file to console.bak, erasing any existing console.bak file. You should include both console.log and console.bak in your data collection. Make sure you copy them to a safe place before restarting the enterprise server.

Parent topic: Enterprise Server Log Files


To View the Enterprise Server Log Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Home page click Edit to the left of the required server.
  2. Click the Diagnostics tab.
  3. Click the ES Console tab to view the console log, or click the CS Console tab to view the communications process log.
  4. If you want to see the whole log since the server was started, click Show Entire Log. The log opens in a text editor window.
  5. To return to ESMAC, click Back in your browser.
Note: You can display the console log by clicking Display in the Diagnostics group of the left-pane menu when it is available. To return to ESMAC, click Back in your browser.
Parent topic: Enterprise Server Log Files
Parent topic: Work with Servers


Enterprise Server System Directory

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Each Enterprise Server writes log, dump and trace information to files in its System Directory.

The default location for the System Directory is /var/mfcobol/es/region name

Note: This cannot be changed.
Parent topic: Collecting Information
Related information
Moving the Diagnostics Data


Dumps and Traces

Restriction: This topic applies only when the Enterprise Server feature is enabled.

We recommend that you always run a production system with some diagnostics switched on. This is necessary so that you can troubleshoot unexpected problems. Diagnostics consume resources, and there is always contention between problem determination facilities and performance. You need to decide how important it is to be able to diagnose a problem the first time it occurs rather than having to try to recreate it or having to just turn on diagnostics and wait for it to reoccur. We suggest the following level of diagnostics as a minimum:

  • Select "Auxiliary Trace Active".
  • Select the application container (API) trace flag.
  • Select "dump on system abend".

You might also need to turn on tracing for task control (KCP), storage control (SCP) and application container (RTS) components.

  • Producing a core dump for run-time errors
Parent topic: Collecting Information
Related information
To view a dump
To change the trace dataset
To transfer the in-memory trace data to the auxiliary dataset at rollover
casdump
casstart
Starting and Stopping the Directory Server


Producing a core dump for run-time errors

Restriction: This topic applies only when the Enterprise Server feature is enabled.

By default, Enterprise Server does not create a core dump for run-time errors. For example, by default, if the operating system detects a memory access violation caused by your application, no core dump is produced. You must configure the system to produce a core dump for these situations.

Once you have produced a core dump, you can debug the core dump to help determine the cause of the error.

Note:
  • This functionality is available for the Windows and AIX operating systems only.
  • The functionality does not identify memory corruption issues. You can use it to identify application problems only.

To configure the system so that it creates a core dump for run-time errors, you need to create a run-time tunable configuration file, and add the tunable configuration file's details to your Enterprise Server region.

  • To create a run-time tunable file, create a text file, for example COBCONFIG.CORE.TXT with the following entries:
    SET CORE_ON_ERROR=131
SET CORE_FILENAME="core.%p@%t_%d"
  • To add the configuration to Enterprise Server, add the entry to your Enterprise Server region configuration. When you start the region, core dumps will be produced by run-time errors. See the illustration below for an example.
Figure 1. Configuring Enterprise Server core dumps for run-time errors
Configuring Enterprise Server core dumps for run-time errors
Parent topic: Dumps and Traces


Data Capture

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The minimum items for data capture are:

  • Your enterprise server's System Directory, $COBDIR/var/mfcobol/es/WORKAREA/ESName, contains:
    • The console log: console.log and console.bak.
    • The communications process log file or files; see the topic Communications Process Log Files.
    • The trace diagnostic datasets, casauxta.rec and casauxtb.rec.
    • The system abend dump, if one exists (casdumpa.rec, casdumpb.rec or casdumpx.rec).
    • The externally triggered dump (filenames as for the system abend dump).
  • A copy of the file cobver, located in , and that holds the name and version of the product you are using.
  • If it exists, the mf-server.dat file is located in the $COBDIR/etc .
  • The Directory Server configuration directory, usually under the $COBDIR/etc/mfds directory.
  • The Directory Server log file (usually under the /var/mfcobol/logs directory); see the section Directory Server Journal.
  • Logs for other components that may be enabled such as Fileshare.
  • A list of processes running on the machine. You should obtain two lists - one at the beginning of the data capture list, and one at the end. You can obtain this by running the following command :
    ps -ef
  • A list of shared memory areas and semaphores. You can obtain this by running the following command :
    ipcs -a
  • A list of network connections and listening sockets, obtained by running the netstat command.
    Note: The syntax of this command differs between platforms.
  • Optionally, a list of open files. You can obtain this by running the following command :
    lsof

    This command is available from third-party UNIX tool suppliers.

Note:
  • The operating system tools that you can use to obtain information such as the ipcs command provide a range of options. You can obtain advice on the most useful options from Micro Focus technical support.
  • Many of these items are held in the enterprise serve directory, so it's best to start by taking the whole directory

It is important that the data capture process is non-destructive, that is, does not damage a healthy system, and that it is non-blocking, that is, does not wait on anything that may not complete in a sick system.

Parent topic: Troubleshooting
Related information
Communications Process Log Files
System Directory
Directory Server Journal


Checking the Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you take the data capture, you should also check that the communications process (MFCS) is still running. If it is, you can then check what it is currently doing. To do this:

  1. Write down the hostname of the machine where the enterprise server instance is running.
  2. Go to the Enterprise Server Administration Web interface. In the list of servers on the Home page, find the enterprise server instance that you want to check. The Communications Processes column lists one or more communications processes for that server. Write down each of the port numbers shown in the column. (The port number is the last part of the address, after the second colon.)
  3. In a web browser, go to the following URL:
    http://hostname:port/MF_KEEPALIVE

    where hostname is the hostname (or IP address) from step 1 and port is the first port number from step 2.

    If MFCS is working correctly, you should see a response similar to the following:

    Server=ESDEMO
ServerType=GKC
Version=1.2.5
Status=Started
  4. Repeat step 3 using "MF_STATISTICS" instead of "MF_KEEPALIVE". You then see a response showing what MFCS is currently doing, how many conversations it has processed, and other information.

If you are running multiple communications processes, you can check each one in turn using this method. Each of the port numbers you recorded in step 2 corresponds to a communications process. Note that some of your communications processes for a given server may be disabled; they do not need to be checked.

Parent topic: Troubleshooting


Using a Diagnostics Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can obtain the most value from the diagnostics aids if you use a dedicated enterprise server instance solely for investigating problems. This enterprise server instance is a diagnostics server.

You can then generate dumps and traces from the diagnostics server and compare them with the dump and trace data collected from the live server that experienced the problem.

  • Configuring a Diagnostics Server
  • Moving the Diagnostics Data
  • Viewing the Diagnostic Server Console Log
  • Viewing a System Trace: Diagnostics Example
  • Viewing a Dump
Parent topic: Troubleshooting


Configuring a Diagnostics Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A diagnostics server is the same as any other enterprise server instance, that is it does not provide any additional diagnostics facilities.

The only difference is that a diagnostics server is configured not to produce any diagnostic information itself. This allows it to be used to process the diagnostic information from another server. The figure below shows the recommended configuration for a diagnostics server.

Figure 1. Configuration for a Diagnostics Server
Configuration for a Diagnostics Server
Parent topic: Using a Diagnostics Server


Moving the Diagnostics Data

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before you can start work on the data collected from the server that experienced the problem, you need to copy it into the diagnostics server. Here are the commands you need to move the collected data and the log files into a diagnostics server, assuming that:

  • You are in the System Directory of the enterprise server that experienced the problem
  • The diagnostics server is using the default System Directory location

In the examples below, Enterprise Server is installed as part of Visual COBOL:

cp *.rec $COBDIR/var/mfcobol/es/WORKAREA/diagnostics-server-name
cp console.log $COBDIR/var/mfcobol/es/WORKAREA/diagnostics-server-name/console.aux
cp console.bak $COBDIR/var/mfcobol/es/WORKAREA/diagnostics-server-name/console.bak

Here is a sample script that copies the required data to a diagnostics server called diagnose.

cp *.rec $COBDIR/var/mfcobol/es/WORKAREA/diagnose
cp console.log $COBDIR/var/mfcobol/es/WORKAREA/diagnose/console.aux
cp console.bak $COBDIR/var/mfcobol/es/WORKAREA/console.bak

Restart the server that experienced the problem after you have moved the data to the diagnostics server.

Parent topic: Using a Diagnostics Server
Related information
Enterprise Server System Directory
Moving the Diagnostics Data


Viewing the Diagnostic Server Console Log

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Extra options exist for viewing a diagnostic server's console log. These commands are available with any enterprise server instance, but they are useful only in the context of a diagnostics server with the diagnostic files loaded from the problem server, copied using the commands described in Moving the diagnostics data.

To access the diagnostic server's ESMAC screen:

  1. In the Enterprise Server Administration screen, click the diagnostic server's Details button to access the server's Details screen.
  2. On the Details screen, click the ES Monitor & Control button to access the diagnostic server's ESMAC screen.

To use these extra options:

  • In the left pane in the Diagnostics area, select the Log and the C/x radio buttons (for current), then Display to view the current console log file, that is, the console.log file of the diagnostics server.
  • In the left pane in the Diagnostics area, select the Log and B radio buttons (for backup), then Display to view the backup console log of the problem server (console.bak). Note that this works only if you copied the data collection into the diagnostics server after you started it, because the process of starting it replaces the backup console log from the problem server with the backup console log of the diagnostics server
  • In the left pane in the Diagnostics area, select the Log and A radio buttons (for auxiliary), then Display to view the console log of the problem server (copied to console.aux)
Parent topic: Using a Diagnostics Server


Viewing a System Trace: Diagnostics Example

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This subject is covered in the help topic To view a system trace. However, the options are complex and it is worth looking at an example.

To obtain a trace of the system trace table:

  1. In the Enterprise Server Administration screen, click the diagnostic server's Details button to access the server's Details screen.
  2. On the Details screen, click the ES Monitor & Control button to access the diagnostic server's ESMAC screen.
  3. In the Diagnostics area in the left pane, select the Trace radio button, and select either the A or B radio button to select the A or B dataset. (Don't select C, since the in-memory trace table belongs to the diagnostics server).
  4. In the Blocks field, specify the number of trace blocks that are to be aggregated into one trace index entry.
  5. Click Display.
Figure 1. Trace Index Page
Trace Index Page

Each block is the same size as the system trace table, that is, it contains the number of trace entries specified in Trace Table Size on the Edit Server page for the server. The index entries are displayed with a timestamp against each one. This is the timestamp of the first trace entry in each set of blocks. These timestamps help you narrow down your search to particular events.

To view the actual trace, go to one of the index entries, and make selections in the following fields:

  • In Blocks (immediately to the right of Details), specify how many blocks you want to be included in the trace. This defaults to the value you entered in Blocks in the Diagnostics group of the menu. You can change it to any value you want. Having two Blocks controls helps you control what is displayed in the formatted trace more precisely.
  • In Level, (the next control to the right), specify the level of detail that you want to see in the formatted trace. The options are:
    0 | Service start, module start, module end, service end. This is the default.
    1 | Enterprise server API entries and exits
    2 | Subsystem trace entries
    3 | All entries where it is possible to provide some formatting of the data
    4 | All trace entries
  • In PIDs (next to the right), check the check boxes for the process IDS of the processes in which you are interested. Check boxes are provided for all the processes that have trace entries in the blocks represented by this trace index entry. Process IDS are prefixed with a letter or number indicating the function of the process. The following letters are used:
    C | communications process (MFCS)
    F | Fileshare server (internal)
    J | journal control
    M | server manager
    R | recovery
    S | service execution process (SEP)
    U | unknown
    Z | generic terminal or client
  • In Task IDs (next to the right), check the check boxes for the task IDS of the tasks in which you are interested. Check boxes are provided for all the tasks that have trace entries in the blocks represented by this trace index entry.

The Level, PIDs and Task IDs controls are filters that help you select just the specific information of interest. If you leave the level as 0, the default, and don't check any process IDs or task IDs, you will see the minimum level of information for all processes and tasks that have entries in the block represented by the trace index entry. Note that it is possible to make selections such that no trace information is generated. This happens if you select both processes and tasks, and none of the selected tasks ran on the selected processes; a task cannot run on more than one process. If a task requires communications work, that work has its own process and task, and there is no automated way of relating the two task IDs. You always see the first trace entry in the block, irrespective of filtering.

Here is an example of how you can use the controls to select the information you want to see. Suppose you specify 10 in Blocks in the Diagnostics group of the menu. There are actually 60 blocks of information in the dataset, so 6 index entries are displayed. Suppose you were interested in a particular SEP, which you can see listed in the third and fourth index entries. You might then specify 20 in Blocks for the third index entry, check the box next to the process ID for the SEP, then click Details. Now you can only see trace entries for that SEP, in all the blocks that contain them, starting with the first block of the third index entry.

Each trace entry contains the following information:

Heading | Contents
None | An interpretation of the traced event, if one can be supplied
Seq | Sequence number of the entry in ascending order
Task-Nbr | The five-digit task number
ProcessID | The five-digit process ID
ID | the ID of the event, command, or instruction that was traced. This is a four-byte hexadecimal number.
hhmmsshh | A time stamp that indicates when the trace entry was written. The time stamp is in hours, minutes, seconds, and hundredths of a second.
aaaa bbbb | Eight bytes of entry-specific data

When you have finished viewing a trace, click Back to return to the trace index page.

Parent topic: Using a Diagnostics Server
Related information
To View a System Trace


Viewing a Dump

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic provides an example of viewing a dump to locate the source of a problem.

You can obtain either a summary or a detailed dump. The summary information is included at the end of a detailed dump. Dumps whether summary or detailed include both system traces and local traces (traces for SEPs).

To access the diagnostic server's ESMAC screen:

  1. In the Enterprise Server Administration screen, click the diagnostic server's Details button to access the server's Details screen.
  2. On the Details screen, click the ES Monitor & Control button to access the diagnostic server's ESMAC screen.
  3. In the Diagnostics area in the left pane, select the Dump radio button, and select either the A or B radio button to select the A or B dataset. Select C to select the dump X dataset (the one created by an externally triggered dump).

    Ignore Blocks - it has no effect on the output.

  4. Click Display.
Figure 1. Dump Index Page
Dump Index Page

The index entries are displayed with the following information against each one:

  • The process ID
  • A code that helps identify the dump
  • The origin of the dump request
  • A date and timestamp

To view a dump, go to one of the index entries, and in Level, (the third control to the right), specify the level of trace detail that you want to see in the formatted dump. The options are:

0 | Service start, module start, module end, service end.
1 | Enterprise server API entries and exits
2 | Subsystem trace entries
3 | All entries where it is possible to provide some formatting of the data
4 | All trace entries. This is the default

Local trace tables (traces for SEPs) only have levels 0 and 1.

Note that this option has an effect on what you see in a detailed dump, but not in a summary dump.

Then click Details to see a full dump or Sum to see a summary dump.

When you have finished viewing a dump, click Back to return to the dump index page.

Parent topic: Using a Diagnostics Server
Related information
To View a Dump


What You Can Do with Dumps and Traces

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section details the tasks that you can perform on dumps and traces.

  • To Change the Trace Dataset
  • To Configure Dumps
  • To initiate a system dump
  • To specify what information is traced
  • To View a Dump
  • To View a Local Trace for a Client Process
  • To View a Local Trace for a SEP
  • To View a System Trace
  • To Configure Run-time Core Dumps
Parent topic: Troubleshooting


To Change the Trace Dataset

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To change the trace dataset

  1. In the left pane, click Control.

    The Control page is displayed.

  2. Click Trace n, Switch (where n is A or B). If the dataset is currently set to A, it is switched to B. If it is B, the dataset is switched to A.
Note: By default, the enterprise server uses the A dataset to record trace information.
Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To Configure Dumps

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To configure a dump:

  1. Click Control.

    The Control page is displayed.

  2. Check Dump on Abend, Sys if you want a dump created if the system abends. Click Dump on Abend, Trans if you want a dump created if the service abends. You can check both check boxes if you want to create dumps on both types of abend.
Note: By default, the enterprise server uses the A dataset to record dumps. If you want to change the dataset, click Dump n, Switch (where n is A or B). If the dataset is currently set to A, it is switched to B. If it is B, the dataset is switched to A.
Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To initiate a system dump

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To initiate a system dump

  1. Click Control.

    The Control page is displayed.

  2. Click Dump.
Note: You can also initiate a system dump using Enterprise Server Administration.
Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To specify what information is traced

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To specify what information is traced

  1. Click Control.

    The Control page is displayed.

  2. Check the required check boxes in the Trace Points group.

    The help for the Control page explains the meaning of each check box.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To View a Dump

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To view a dump

  1. Click Dump in the Diagnostics group.
  2. Click A or B to select the dump dataset, or C to select the X dataset.
  3. Click Display.

    A list of dumps is displayed.

  4. For the dump you want to display, in the field below the heading Level, choose a level of trace information to be included in the trace tables in the dump. The larger the number, the more detail will be shown. The options are:
    0 | Service start, module start, module end, service end. This is the default.
    1 | Enterprise server API entries and exits
    2 | Subsystem trace entres
    3 | All entries where it is possible to provide some formatting of the data
    4 | All trace entries

    Each level includes all lower-level information. Local trace tables (traces for SEPs) only have levels 0 and 1.

  5. For the dump you want to display, click Details to see a detailed dump or Sum to see a summary dump.

    The dump is formatted and displayed. To return to ESMAC, click the Back button in your browser.

Note:

The X dataset contains dumps triggered by the external command casdump /d. You use casdump /d when a dump cannot be obtained normally; for example, when the enterprise server is not responding and shared memory is locked. The dataset has the filename casdumpx.rec.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC
Related reference
casdump
Related information
Viewing a Dump
To create an ESMAC user
To start ESMAC for a server
To monitor services
To configure dumps
To initiate a system dump
To specify what information is traced
To change the trace dataset
To transfer the in-memory trace data to the auxiliary dataset at rollover
To view a system trace
To record service input and output
To view a local trace for a SEP
To view a local trace for a client process
To kill a SEP
To reply to an ACCEPT FROM CONSOLE statement
To shut down a server
Troubleshooting


To View a Local Trace for a Client Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To View a Local Trace for a SEP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To view a local trace for a SEP

  1. Click SEPs in the menu.
  2. Click Trace next to the SEP for which you want to view a local trace. Auxiliary processes are listed underneath SEPs, and you can obtain traces for some of them: the Fileshare process, JCP (journal control program), and TDP (extra-partition transient data process).

    The trace is formatted and displayed. To return to ESMAC, click Back in your browser.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC


To View a System Trace

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To view a system trace

  1. Click Trace in the Diagnostics group.
  2. Click A or B to select the dataset, or C to select the in-memory trace table.
  3. Specify the number of trace blocks that are to be aggregated into one trace index entry in Blocks in the Diagnostics group. This defaults to 10.
  4. Click Display.

    A list of traces is displayed: this acts as an index to the detailed trace information. For each entry in the index list the following information is shown, from left to right:

    • The process IDs of all processes that have entries in the blocks represented by this trace index entry.
    • The task IDs of all tasks that have entries in the blocks represented by this trace index entry
    • The date and time stamp of the first entry in the trace.
  5. If you want to change the number of blocks to be included in the Details, specify a new number of blocks in the field immediately to the right of Details and below the heading Blocks (this defaults to the number you entered in the Diagnostics group).
  6. In the next field, below the heading Level, choose a level of tracing where the larger the number, the more detail will be shown. The options are:
    0 | Service start, module start, module end, service end. This is the default.
    1 | Enterprise server API entries and exits
    2 | Subsystem trace entres
    3 | All entries where it is possible to provide some formatting of the data
    4 | All trace entries

    Each level includes all lower-level information.

  7. In the next group of fields, below the heading PIDs, if you don't want to see trace entries for all processes, check the check boxes next to the process IDs that you do want to see details for.
  8. In the next group of fields, below the heading Task IDs, if you don't want to see trace entries for all tasks, check the check boxes next to the task IDs that you do want to see details for.
  9. Click Details for the trace you want to display.

    The trace is formatted and displayed. To return to ESMAC, click Back in your browser.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Administer a Server Using ESMAC
Related information
Viewing a System Trace: Diagnostics Example
To create an ESMAC user
To start ESMAC for a server
To monitor services
To configure dumps
To view a dump
To initiate a system dump
To specify what information is traced
To change the trace dataset
To transfer the in-memory trace data to the auxiliary dataset at rollover
To record service input and output
To view a local trace for a SEP
To view a local trace for a client process
To kill a SEP
To reply to an ACCEPT FROM CONSOLE statement
To shut down a server
Troubleshooting


To Configure Run-time Core Dumps

Restriction: This topic applies only when the Enterprise Server feature is enabled.

By default, Enterprise Server does not create a core dump for run-time errors. To configure an Enterprise Server region to produce a core dump for run-time errors:

  1. Create a run-time tunable text file, for example COBCONFIG.CORE.TXT with the following entries:
    SET CORE_ON_ERROR=3
SET CORE_FILENAME="core.%p@%t_%d"
  2. Access the Enterprise Server Administration screen, and in the Status column, click the Details button for the enterprise server instance.
  3. To add the configuration to enterprise server instance, add the entry to your Enterprise Server region configuration. When you start the region, core dumps will be produced by run-time errors. See the illustration below for an example.

Parent topic: What You Can Do with Dumps and Traces
Parent topic: Monitor Directory Server


Problems Caused by Process Limits

Restriction: This topic applies only when the Enterprise Server feature is enabled.

UNIX systems limit how much of various system resources each process on the system can use. This prevents badly-behaved processes from using all the system resources and tying up the machine so that no other processes can run. In some cases you might need to configure the operating environment for Enterprise Server so that it can use more than the default amount of resources.

Which resources are limited, the default limits for them, and the maximum limits supported by the operating system depend on the version of UNIX and how it is configured on each system. See your operating system documentation for more details. Typically, UNIX systems can limit the memory, the amount of CPU time, and the number of open files (including network sockets) used by each process, and the size of files it creates.

An enterprise server instance might run short on resources if it is required to handle a large client load. The Enterprise Server component which is most likely to encounter resource limits is the Micro Focus Communications Process, mfcs32. There is one mfcs32 process for each started communications process in the started enterprise server.

  • Diagnosing Resource Limit Issues
  • Examining and Changing Resource Limits
Parent topic: Troubleshooting


Diagnosing Resource Limit Issues

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If mfcs32 encounters a memory or stack resource limit, it will typically not be able to create new threads to process additional conversations (until some existing conversations are finished), and might not be able to allocate memory for tasks such as parsing HTTP headers. Typical error messages in the communications console log (log.html) in this situation include:

  • error OS_FAIL: OS reported an error starting thread for conversation
  • HTTP Parser: Unable to allocate 32767 bytes
  • Unable to process conversation 37425 for listener Web Services - closing conversation

If mfcs32 encounters a file descriptor limit, it will be unable to create sockets for new conversations. In this case no error will be logged, but the conversation will be closed immediately, and the client should report an error.

If an enterprise server runs for a very long period of time, one or more enterprise server processes could encounter a CPU time limit. In this case the process will be killed by the operating system. Generally, Enterprise Server will detect this and restart the killed process, but any work the process was doing (running a service if it's a service execution process, or handling client conversations if it's a communications process) will be lost. An error message will appear in the Enterprise Server console log (file console.log) noting that a process was terminated and restarted.

Parent topic: Problems Caused by Process Limits


Examining and Changing Resource Limits

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The system-wide default and maximum values for resource limits depend on UNIX platform and configuration. For more information consult your operating system documentation.

Resource limits can be set for individual processes and the processes they start. For example, if you start an enterprise server from the Enterprise Server Administration Console, it will inherit its resource limits from the Directory Server process mfds32 (which provides the Administration Web interface). Changes to the resource limits when starting the Directory Server will also affect enterprise server processes that are started through the Web interface. If you start an enterprise server from the command line using the casstart command, on the other hand, you can set resource limits in the current shell before running casstart to control resources for that enterprise server.

Resource limits can be examined and changed for the current shell using the UNIX ulimit utility. The exact syntax and output of the ulimit command depends on UNIX version, so consult your documentation for the specific details. Typically, however, ulimit -a displays all the current resource limit settings, as follows:

$ ulimit -a
time(seconds)        unlimited
file(blocks)         2097151
data(kbytes)         131072
stack(kbytes)        32768
memory(kbytes)       32768
coredump(blocks)     2097151
nofiles(descriptors) 2000

This is the output from an AIX 5.2 system. It shows that there is no CPU time limit in effect for processes started in this shell and that regular files and core dump files are limited to 2097151 512-byte blocks (1 GB in total). The data, stack, and memory limits are all limitations on how much memory the process can use. For enterprise server, the stack setting limits how many threads mfcs32 can create to handle conversations, and the data setting limits how much virtual memory mfcs32 can allocate to process conversations. The memory setting controls how much physical memory - RAM - a process can use, and is usually less important for enterprise server. The final limit is the number of file descriptors. mfcs32 requires a few descriptors for various purposes such as its log file, plus one for each listener; the rest are for individual conversations with clients. In this example, mfcs32 would be limited to something less than 2000 clients connected simultaneously.

There are two kinds of resource limits set by the ulimit command: hard and soft. By default, ulimit shows and sets soft limits. The soft limits are the ones that actually affect processes; hard limits are the maximum values for soft limits. Any user or process can raise the soft limits up to the value of the hard limits. Only processes with superuser authority can raise the hard limits.

For example, if you were encountering a resource limit problem with an Enterprise Server, and you wanted to raise the stack limit to see if that corrected the problem, you might try the following:

  1. Display the current soft limit for stack:
    $ ulimit -s
   32768
  2. Display the current hard limit (maximum) for stack:
    $ ulimit -H -s
   4194304
  3. Set the stack soft limit to some value between the current and the maximum:
    $ ulimit -s 65536
  4. Start the enterprise server with the new stack limit in effect:
    $ casstart

Note that in step 4 you start the enterprise server from the command line. If you wanted to start the enterprise server from the Administration Web interface, you would have to start the Directory Server from the command line in this shell, after raising the limit, and then start the enterprise server from it.

Parent topic: Problems Caused by Process Limits


Enterprise Server Administration Console Help Pages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The topics in this section contain the context-sensitive information that relates to the Enterprise Server user interface.

A version of this help is available directly from the Enterprise Server administration user interface.

Note: While the information available from the user interface still applies, this version is the most current.
  • Enterprise Server Administration Side Bar Menu
  • Enterprise Server Administration Home Page
  • Edit Server Instance Properties
  • Listeners
  • Services
  • Handlers
  • Packages
  • Security Configuration Screen Help
Parent topic: Enterprise Server configuration and administration


Enterprise Server Administration Side Bar Menu

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The sidebar appears at the left of the Enterprise Server Administration screen. It contains the folllowing areas and options:

Home

Click this to return to the Home page.

Actions

These menu options provide administrative actions. The options that are displayed in this area varies depending on the user's permission level.

Renew

Click this to refresh the IP address information cached by your Directory Server. Use this option when the IP address of the machine running your Directory Server changes.

Directory Server uses the IP address to locate the servers that it manages. When the cached IP address is out of date, Directory Server may be unable to connect to its servers and may report inaccurate information to clients.

Export

Click this to show the Export page. This page enables you to save a copy of the whole repository to a location of your choice. This menu option is available only if you logged on with Administrator or Schema Administrator permission level.

Import

Click this to show the Import page. This page enables you to update the repository with additional objects from an import directory. Imported objects can include servers (along with all of their child objects), and Security Manager definitions. This menu option is available only if you logged on with Schema Administrator permission level.

Delete All

Click this to show the Delete confirmation page. This page enables you to confirm that you want the repository to be completely erased and all registered objects to be deleted. This menu item is available only if you logged on with Schema Administrator permission level.

Logon

Click this to show the log on page. This menu option is shown only if the session is not currently logged on and the User Access setting on the Options page is "Restricted".

Logoff

Click this to log off from an administrative session that is currently logged on. There is no log off confirmation. This menu option is shown only if the session is currently logged on and the User Access setting on the Options page is "Restricted".

Configure

The heading for the menu option that enables you to configure Directory Server. This menu heading and its associated menu option are available only if you logged on with Administrator permission level or higher.

Options

Click this to show the Directory Server Options page. This page enables you to configure the Directory Server.

Security

Click this to show the pages used for configuring security options.

Display

The heading for menu options that enable you to view information about the state of the Directory Server and about the events that have taken place on the server.

Directories

Click this to show the Directories page. This page lists all the instances of Directory Server that are running on the network and using the default Directory Server port (86).

Statistics

Click this to show the Statistics page. This page shows statistics and status information about Directory Server.

Sessions

Click this to show the Sessions page. This page shows the list of currently logged on Web browser client sessions, and also any bound program client sessions.

Journal

Click this to show the Journal page. This page shows the Directory journal, which is a record of Directory Server activity.

Shut Down

Click this to show the Shut Down confirmation page. This page enables you to shut down the Directory Server. This menu option is available only if you logged on with Schema Administrator permission level This menu option is available only if you logged on with Schema Administrator permission level and Directory Server is not running as a Windows service.

Help

The heading for menu options that enable you to view documentation about the Directory Server and Enterprise Server Administration.

This page

Click this to view help for the page you are currently viewing and for all the controls on the page.

Contents

Click this to view the Contents of the Enterprise Server documentation.

CAUTION:
This version of the help has not been updated to reflect the latest product changes. For the latest help, go to the Micro Focus Product Documentation site.
Note:

For this link to work, you must be using an enterprise server that has a Web listener with the following entry in the [virtual paths] section:

  • For Windows systems:
    docs=<ES>/help
  • For UNIX systems:
    docs=<ES>/docs/html

This enterprise server must be started.

The default enterprise server, ESDEMO, has a web listener with this configuration information. When you create a new enterprise server, a Web listener with the required configuration information entry is automatically created.

Support

Click this to contact Micro Focus Technical Support via the Supportline website to report problems or ask any questions about using Micro Focus software.

Feedback

Click this to open your email client and send general feedback to Micro Focus.

  • Export
  • Import Server Information (Page 1 of 4)
  • Configure Repository Options
  • Display Directories
  • Display Statistics
  • Display Sessions
  • Journal
Parent topic: Enterprise Server Administration Console Help Pages


Export

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Target directory

Use this page to save all server information in the Directory Server repository to a backup location.

Specify the name of the directory the server information will be exported to. If the directory does not exist, the export process will attempt to create it.

Export options:

You use these radio buttons to choose which information is included in the export. You can choose to:

  • Export Enterprise Server configuration and Security Manager definitions

    This will export all of the configuration information for your Enterprise Servers. It will also export the pool of Security Manager definitions, and the Security Manager lists for your servers, along with security configuration details. (A Security Manager list indicates which managers are used by a given server.)

  • Export just the current Enterprise Server configuration

    The Security Manager definitions, Security Manager lists and security configuration details will not be included in the export.

  • Export just the Security Manager definitions

    Only the pool of Security Manager definitions will be exported. This will not include the security configuration details or the Security Manager lists.

    Note:

    Security Manager lists are only exported when you choose the first of these options.

When you import, you can choose whether to include or exclude security details, if these have been exported. Where the import excludes the security details, or where the security details were not included in the export, the imported servers will use the Default ES Security configured on the importing system.

Where the import includes security details, all existing security information - the Security Manager pool, Security Manager lists and other security configuration details - will be removed and replaced with the imported information. One consequence of this is that servers that are not replaced during the import will have their security details set to use the Default ES Security configuration.

Parent topic: Enterprise Server Administration Side Bar Menu


Import Server Information (Page 1 of 4)

Use this page to import server definitions. The effect of this is to add the servers and their child objects (services, listeners, etc.) to your current repository.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Selected source directory containing server data to be imported
Specify the type and location of the directory from which data is to be imported. The source directory should have been previously populated by a repository export, an export of an individual Enterprise Server, or a compatible process. It can be a file system location or an LDAP repository.

For file system storage, the location is the directory in which the exported data is stored.

For LDAP storage, the location is the address of the LDAP server containing the exported data.

Note: When you specify ldap:// as the directory type, additional fields are displayed for specifying the container in which the data is stored, and the LDAP user credentials required to read from the container.
Repository Container Distinguished Name
The distinguished name of the LDAP container in which the exported data is stored.
User DN:
The distinguished name of the LDAP user with which to access the repository. This user must have permission to read from the container.
User Password:
The password of the user with which to access the repository.
Recent directories
This contains a list of directories from which you have previously imported data.
Note: By default the directory will only be added to the list if the import is successful, but you can choose to include the directory even if the import fails.
Delete
This button enables you to remove an entry from the list of recent directories.
Parent topic: Enterprise Server Administration Side Bar Menu


Configure Repository Options

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configuration settings for the Directory Server.

Repository Location

Specify the type of storage and the location containing the repository. You can store the repository in the file system or in an LDAP repository.

For file system storage, the location is the directory in which the repository data will be stored.

For LDAP storage, the location is the address of the LDAP server that will be used.

In order to store the repository in an LDAP server, the server must be updated to support the Micro Focus configuration objects.

CAUTION:

If you change the location and the destination already contains a repository, you will be warned and given the opportunity to overwrite it or to cancel the operation.

Note:

When you specify ldap:// as the storage mechanism, additional fields are displayed for specifying the container in which the data will be stored, and the LDAP user credentials required to write to the container.

Repository Container Distinguished Name

The distinguished name of the LDAP container in which the repository is to be stored.

User DN:

The distinguished name of the LDAP user with which to access the repository. This user must have permission to read and write to the container.

User Password:

The password of the user with which to access the repository.

Parent topic: Enterprise Server Administration Side Bar Menu


Display Directories

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of all MF Directory Server instances that are running on the local network and using the default MF Directory Server port (86).

Version

Shows the version of the Directory Server software in use.

IP Address

Shows the IP address of the machine on which the Directory Server is running.

DNS Resolved Hostname

Shows the DNS-resolved hostname of the machine on which the Directory Server is running. If there is a right-pointing arrow next to this name, you can click it to open Enterprise Server Administration for the instance of Directory Server running on the other machine. What you can do depends on how security has been configured on the other machine.

Parent topic: Enterprise Server Administration Side Bar Menu


Display Statistics

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view statistics and status information about the Directory Server.

Repository

This table shows information about the repository.

Location

Shows the directory containing the repository of all registered object information. If the path is relative it is relative to the Directory Server current directory.

Status

Shows the last action performed on the repository.

Objects

This table contains statistics about the objects stored in the local repository.

Servers

Shows the number of servers stored in the local repository.

Communications processes

Shows the number of communications processes stored in the local repository.

Listeners

Shows the number of listeners stored in the local repository.

Services

Shows the number of service operations stored in the local repository.

Handlers

Shows the number of request handlers stored in the local repository.

Packages

Shows the number of implementation packages stored in the local repository.

XA Resources

Shows the number of defintions of XA resources stored in the local repository.

Total Count

Shows the total number of objects stored in the local repository.

Request Processing

This table contains information about incoming client requests.

TCP Requests

Shows the number of TCP requests received since the Directory Server was started. These can come from either program clients or Web browser clients.

UDP Requests

Shows the number of UDP requests received since the Directory Server was started. These come only from program clients.

MLDAP Requests

Shows the number of TCP or UDP MLDAP requests received since the Directory Server was started. These can be generated by enterprise servers or program clients

Maximum Thread Count

Shows the maximum number of concurrent MLDAP requests that have been processed at any time since the Directory Server was started

Current Thread Count

Shows the number of MLDAP requests currently being processed.

Options

This table contains some of the current Directory Server option settings.

User Access

Shows what level of access is available to users. Possible values are:

Restricted | Access is allowed only by an authorized user who has logged on.
Unrestricted | Access is allowed by any user.
Server Monitor

Indicates whether the server monitor is currently active or not. The server monitor checks whether all enterprise servers registered with the Directory Server and not marked "Stopped" are responding to potential client requests. If they are, their status is marked as "Started", otherwise, if they are currently marked as "Started" and they are not responding, they are marked as "Not Responding".

Having the server monitor on ensures that the Current status field for a server is up to date, even if the server itself cannot contact the Directory Server for some reason, for example, a network connection or machine failure.

You can enable and disable the server monitor and change the time interval between checks on the Configure Options page.

Journal Level

Indicates what level of journal logging is in force.

Paths

This table contains the paths that the Directory Server is using for its own resources.

COBDIR

Shows the setting of the COBDIR environment variable, which holds the location of your installed development system or standalone Enterprise Server. This field might be empty if the Directory Server is being run as a Windows service, as this environment variable is not one that is set by the Windows system.

Executables

Shows the location of the system programs that make up Enterprise Server.

Artwork

Shows the location of the graphics files that the Directory Server uses in its interface.

Help and documentation

Shows the location of the documentation for Enterprise Server.

Trace and journaling

Shows the location of the trace files and journals created by Enterprise Server.

Parent topic: Enterprise Server Administration Side Bar Menu


Display Sessions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of currently logged on Web browser clients and program clients. The sessions may be really active, or they may be dormant but not yet removed because the time period between inactivity and removal has not yet been exceeded.

Session ID

Shows the unique identifier string of the session. The session ID is in the format userid-string where userid is the user ID that was used to authenticate the session and string is a unique internal identifier for a Web browser session. string is not present for a program client.

Last Active

Shows the local date and time that the session last requested a response from the Directory Server, for example, a browser refresh or a client program request.

Permission Level

Shows the permission level of the session user. The possible values are:

Unauthenticated | The user is a program client that is performing a query and does not need to be authenticated.
Modify | Values stored in the schema can be modified.
Add/Delete | Values stored in the schema can be modified and objects can be added and deleted. This is normally the highest permission level a program client would need.
Administrator | All of the above, plus objects can be backed up, imported, and the Directory Server can be remotely terminated.
Schema Administrator | All of the above, plus users can be added, modified and deleted and the entire repository can be deleted.
Session Type

Shows the type of user session. The possible values are:

UI | Web browser client
API | Program client
Parent topic: Enterprise Server Administration Side Bar Menu


Journal

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view the journal, a file that records some of the Web browser client and program client activity occurring on the Directory Server.

Note:
  • You can scroll up and down the list of entries using the scroll buttons on the right-hand side of the table.
  • The most recent entries are shown first.
Entries generated

Shows the total number of journal entries generated since this journal file was started. This could be the same or more than the value in Entries held, depending on whether the oldest entries have been overwritten by more recent ones.

Entries held

Shows the total number of journal entries currently stored in the journal file. The maximum value is determined by the configured maximum journal file size; once it is reached, new journal entries overwrite the oldest journal entries.

Journal Size

Shows the current size of the journal file in bytes.

Entry

Shows the entry number of the journal record. When the journal file is restarted or deleted, the entry number is reset back to 1, and is sequentially incremented for each following journal entry.

Time

Shows the local date and time that the journal record was written to the journal file.

Requester

Shows the unique identifier string associated with a particular session. For a Web browser session logged onto the user interface, this is the same identifier as appears in the top right-hand corner of the Web page. For a program client session, the source network address for the request is also shown.

If no requester identifier is shown, the journal event was generated by an internal action or there was no information available about the requester.

Event

Shows the text of the journal event, up to 128 characters.

Green text indicates that the journal event has been generated by program client requests.

Red text indicates that the journal event has been generated by Web browser requests.

Black text indicates that the journal event has been generated by the Directory Server itself.

Delete

Click this to delete this journal and start a new one. You might want to do this if you are debugging a problem with a service and you want a well-defined journal starting-point.

Export As Text

Click this to export the journal entries to a text file. The text file will be called journal.txt and will be saved in your Documents and Settings\All Users\Application Data\Micro Focus\NetExpress\5.0 directory on Windows or your /var/mfcobol/logs directory on UNIX. You might do this to load the journal file in a text editor to search for events involving specific objects or to annotate entries.

If the journal.txt already exists, it will be overwritten.

Parent topic: Enterprise Server Administration Side Bar Menu


Enterprise Server Administration Home Page

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Important: Use the Help > This Page option in the left side-bar to display up-to-date context help on the current Enterprise Server screen. To access up-to-date Enterprise Server product help, go to the Micro Focus Product Documentation site.

This is the Enterprise Server Administration home page that lists the Enterprise Server instances. It is displayed:

  • When you have just logged onto Enterprise Server Administration
  • Any time you click Home at the top of the menu bar on another page.
You use this page as a starting point for all the administration functions. From it you can:
  • Add a server
  • Change the attributes of a server
  • Change the status of a server
  • Go to a more detailed view of the listeners, services, request handlers and implementation packages.
Note: The options available to you depend on the permissions granted to the user groups of which your user account is a member. Those options that are not available to you are hidden.

Use the side bar menu items to access your installation's configuration options, maintained on the Micro Focus Dirctory Server (MFDS).

Expand/Contract button

Click [image] in the left-hand corner of the servers table to see an expanded version of the information in the Objects column, or the minus icon ( [image]) to see a contracted version of the information in the Service Listeners, Services, Request Handlers and Implementation Packages columns.

Refresh Icon

Click Refresh to update the display to show changes in the server status and attributes.

Show

Specify the number of servers to show at a time. Click Refresh to update the screen display.

Previous

Click this to view the previous page of servers. You can click this only if the number of servers is greater than can be shown on one page.

Next

Click this to view the next page of servers. You can click this only if the number of servers is greater than can be shown on one page.

Filter

Click this to update the display according to the Type, Name and Status attributes selected.

Filter by Type

Select the type of server from the drop-down list that you want to be displayed in the server list. Click Refresh to update the screen display with your selection.

Filter by Name

Type the name of the server you want to see in the server list. You can use wildcard characters '*' and '?' to modify your criteria. Click Refresh to update the screen display with your selection.

Filter by Status

Select the status from the drop-down list to display a list of matching servers. Click Refresh to update the screen display with your selection.

Delete

Click this to delete this server. You can see this only if this server is a CCI server.

Edit

Click this to edit configuration settings for this server.

Type

Shows the server type. There are two types of server:

  • MFES

    A Micro Focus enterprise server. This is a server type that provides a run-time environment for COBOL programs running as services.

  • MFCCI

    A Micro Focus Common Communications Interface server. This is a server that provides services using the Common Communications Interface (CCI), using the Directory Server as a naming service instead of registering with a CCITCP2 process.

The icon in the Type column will display '64' if the server has been set up for 64-bit working mode.

You can start and stop enterprise servers using Enterprise Server Administration. You cannot start and stop MFCCI servers from Enterprise Server Administration; if an MFCCI server is running on the network and has been configured to use the Directory Server, it appears in the list of servers automatically, with the status "registered". For more information about CCI, see your Configuring CCI book.

Name

Shows the name of the server.

Current Status

Shows the current status of this server. The possible values are:

Stopped | The server is currently not running.
Stopping | The server is currently in the process of terminating. This is normally a short-lived status value which should be shortly followed by a change to the value "Stopped".
Started | The server is currently running and can respond to client and server requests.
Starting | The server is currently in the process of starting. This is normally a short-lived status value which should be shortly followed by a change to the value "Started".
Not Responding | The server process was previously marked as "Started", but the server monitor has subsequently not been able to contact it. There may be some network connection error, or the server itself may have abnormally terminated without first marking itself as "Stopped".
Invalid | An error has occurred such that it has not been possible to set the status to any other value.
Registered | This status is applicable only to CCI servers. It indicates that the Directory Server has been notified that a CCI server has started.
Start

Click this to start the server. You cannot see this push button unless the server has the status "Stopped" .

Current Status Details

Click this to move to a page giving more detailed information about the current status of the server. You cannot see this push button when the server has the status "Stopped".

Stop

Click this to start the server. You cannot see this push button unless the server has the status "Started" or "Not Responding".

Communications Processes

Lists the communications processes owned by the enterprise server. By default an enterprise server owns one communications process; you can create additional ones. For each process the following information is shown:

  • The number of the process. Numbers are allocated from 1 sequentially.
  • The network address used by the communications process to accept incoming client requests. The format is:

    protocol:ip-address:port

    where:

    • protocol is tcp.
    • ip-address is the IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the enterprise server when it starts.
    • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the enterprise server when it starts.
  • The TCP/IP hostname that is equivalent to the IP address.

The total number of listeners owned by all the communications processes.

Listeners Details

Click this to move to a page giving more detailed information about the service listeners owned by the communications processes.

Licenses

Shows license information. The number before the slash is the number of licenses allocated to this server. When the server is stopped a dash is displayed, because the number of licenses that will be allocated is unknown until the server is started. When the server is running an asterisk can be displayed, indicating that unlimited licenses were allocated. The number after the slash is the number of licenses requested by this server.

Last Status Change

Shows the date and time that the server's current status was last updated; this is local to the machine where the Directory Server is running. You can see this only in the expanded view of the Home page.

Status Log

Shows information about the most recent event that occurred on this server, and how long the server has been in its current state.

Objects

Shows how many of each type of object (services, handlers, packages) the server owns. This is a summary view - it changes when you click the Expand the plus button button

Services

Shows a list of the service operations registered with the Directory Server. If there are more than five, only the first five are shown.

Service Details

Click this to move to a page giving more detailed information about the services registered with the Directory Server.

Request Handlers

Shows a list of the request handlers registered with the Directory Server.

Request Handlers Details

Click this to move to a page giving more detailed information about the request handlers registered with the Directory Server.

Implementation Packages

Shows a list of the implementation packages registered with the Directory Server. If there are more than five, only the first five are shown.

Implementation Packages Details

Click this to move to a page giving more detailed information about the implementation packages registered with the Directory Server.

Description

Shows a description of the server.

Add

Click this to add a new server.

  • Add Server instance
  • Delete Server instance
  • Start Server confirmation
  • Stop Server Confirmation
Parent topic: Enterprise Server Administration Console Help Pages


Add Server instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to provide the attributes for an enterprise server (MFES).

Note:

For more information about the configurable attributes of servers, see the chapter Configuration in your Configuration and Administration Guide.

Name

Shows the name of the server.

Server Address

Specify the network address used by the server to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the enterprise server when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the enterprise server when it starts.

If this network address is not unique in the repository, this might cause enterprise server startup problems.

System Directory

Specify the location for system work files output by the Enterprise Server, such as the console log, and trace and dump diagnostics files. This directory cannot be shared between Enterprise Servers. The default is /var/mfcobol/es/es-name (where es-name is the name of the enterprise server).

If you specify a directory in this field, that directory must exist; Enterprise Server does not create it for you.

Working Mode

Choose whether this Enterprise Server is to run 32-bit or 64-bit applications.

A 32-bit working mode server can run only 32-bit applications. A 64-bit working mode server can run only 64-bit applications.

You cannot change the working mode of the server once it has been created; you can however, change the mode when you copy or import a server.

Startup Options

Use these fields to specify the server configuration you want when the server first starts up. Any changes you make to these fields while a server is running do not take effect until the next time you start the server.

Shared Memory Pages

Specify the number of shared pages in memory to be reserved for all the processes that run in the Directory Server. Each page is 4KB long.

Service Execution Processes

Specify the number of service execution processes that are to be started at server initialization.

Shared Memory Cushion

Specify the number of 4KB pages that should be reserved from the shared memory pages to allow the server to continue processing when the shared memory allocation is too small for the operational requirements of the server. The range is 1 through the number of shared memory pages.

Trace Table Size

Specify the number of entries the trace buffer can hold before it wraps back to the start. (The trace buffer is also written to disk at this point if you checked Auxiliary Trace Active.) A value of 2 means that there is space for only one entry, and if you checked Auxiliary Trace Active each entry is written straight out to disk. Each entry is 24 bytes long.

Local Trace Size

Specify the number of entries the local trace table can hold before it wraps back to the start. A value of 0 (zero) means that no local trace table is allocated. Each service execution process has its own local trace table. Each entry is 24 bytes long.

Maximum Diagnostics File Size

Specify the maximum size of the auxiliary trace and dump file in kilobytes. A value of 0 (zero) means that there is no maximum size.

Requested Licenses

Specify the number of licenses this enterprise server requires.

Cold Start Diagnostics File

Check this to indicate that the auxiliary trace and dump files are to be deleted when the server starts.

Dump on System Abend

Check this to indicate that the server should produce a dump if one of its own processes, such as a service execution process, terminates abnormally. The dump information can help you to determine the cause of the abnormal termination

Auxiliary Trace Active

Check this to indicate that trace records are to be flushed to disk before the trace table is overwritten. You should do this only if you have adequate disk space available, since the file can become very big very quickly. If you have a high-activity system use this field in conjunction with Maximum Diagnostics File Size to limit the disk usage. Writing out to a file also degrades performance.

Show Local Console

Check this if you want to see a text window containing enterprise server messages while the server is running. the messages are written to a file called console.log, in the directory specified in System Directory. You can see the text window only on the machine running the enterprise server. The system messages are also available on the Enterprise Server Console page.

Trace Flags

Use these flags to control what information is written to the trace file for this server. Any changes you make to these fields while a server is running take effect immediately.

Task Control

Check this to indicate that the server is to trace its task control component.

Storage Control

Check this to indicate that the server is to trace its storage control component.

Table Management

Check this to indicate that the server is to trace its table management component.

Application Container

Check this to indicate that the server is to trace its application container component.

Request Handler

Check this to indicate that the server is to trace its request handler component.

RM Interface

Check this to indicate that the server is to trace its resource manager interface component.

Communications

Check this to indicate that the server is to trace its communications component.

Exit

Check this to indicate that the server is to trace user and system exits.

Configuration Information

Specify textual configuration information that determines the start-up and run-time behavior of the server. Optional. For details of the valid entries, see the section Configuration Information in the chapter Servers in your Configuration and Administration Guide.

Description

Specify a text description of the server, for example, its purpose and owner. Optional.

Add

Click this to add the new server to the Directory Server repository.

Back

Click this to return to the previous page.

Parent topic: Enterprise Server Administration Home Page


Delete Server instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete the selected server.

Note:

Deleting a registered server may cause application connection errors and loss of data.

Type

Shows the server type. There are two types of server:

  • MFES

    A Micro Focus enterprise server. This is a special server type that provides a run-time environment for COBOL programs running as services.

  • MFCCI

    A Micro Focus Common Communication Interface server. This is a server that provides services using the Common Communication Interface (CCI), using the Micro Focus Directory Server as a name server instead of registering with a Micro Focus CCITCP2 process.

Name

Shows the unique name of the server.

Status Log

Shows information about the most recent event that occurred on this server.

Services

Shows the number of services registered with this server.

Description

Shows a text description of the server.

Stop server before deleting it

Check this if you want the server to be stopped before it is deleted.

Parent topic: Enterprise Server Administration Home Page


Start Server confirmation

Use this page to confirm user credentials for starting an enterprise server.

Type

Shows the server type. The only type of server you can stop is an MFES server. MFES stands for Micro Focus enterprise server. This is a server type that provides a run-time environment for COBOL programs running as services. MSS in brackets after MFES indicates that the server has Mainframe Subsystem Support (MSS) enabled.

Name

Shows the name of the server.

Status Log

Shows information about the most recent event that occurred on this server, and how long the server has been in its current state.

Description

Shows a description of the server.

Security settings

This section indicates whether the server is using its own security settings and associated security manager list, or the Default ES Security configuration settings, which can be shared by multiple servers.

Where it is using its own security settings, the security managers in its security manager list are displayed.

Start processes as

This specifies the operating system account under which the enterprise server will run.

Use Enterprise Server credentials of

When an enterprise server starts, it connects to Directory Server to obtain its configuration details and, later in the startup process, to update Directory Server information. To do this, it requires Directory Server user credentials (that is, credentials that Directory Server will verify and authorize). In order to update the Directory Server information, this user must be granted modify permission on the appropriate enterprise server resource within Directory Server.

The startup process also requires user credentials that the enterprise server will verify and authorize. In order to run the command used to start the enterprise server, the user must have Alter permissions on the casstart resource within the OPERCMDS resource class.

It is important to note that the enterprise server is a separate security domain from the Directory Server. For example, it may be using different security configuration and different security managers.

You can specify that startup should use built-in default users or the credentials with which you are currently logged on to Enterprise Server Administration. Alternatively, you can specify a different username and password.

If you use the currently logged on user, or specify alternative user credentials, you must ensure that the user is present in both the Directory Server and the enterprise server security domains. Within the Directory Server domain, the user must have modify permission on the appropriate enterprise server resource within the Servers resource class. Within the enterprise server security domain, the user must have alter permissions on the casstart resource within the OPERCMDS resource class.

Note:

Usernames longer than 8 characters cannot be used for MSS. This restriction includes using them to start CAS. Therefore, if you sign on with a username longer than 8 characters, you will not be able to use the currently logged-on administration user option.

Parent topic: Enterprise Server Administration Home Page


Stop Server Confirmation

Use this page to confirm that you want an enterprise server to be stopped.

CAUTION:

Stopping a server might cause application connection errors and loss of data.

Type

Shows the server type. The only type of server you can stop is an MFES server. MFES stands for Micro Focus enterprise server. This is a server type that provides a run-time environment for COBOL programs running as services. MSS in brackets after MFES indicates that the server has Mainframe Subsystem Support (MSS) enabled.

Name

Shows the name of the server.

Status Log

Shows information about the most recent event that occurred on this server, and how long the server has been in its current state.

Services

Shows how many service operations are registered with the enterprise server.

Description

Shows a description of the server.

Clear dynamically assigned address values

Check this to indicate that you want addresses and port numbers that were dynamically assigned when you created new communications processes and listeners to be cleared.

Restart server when it is stopped

Check this to indicate that you want the server to stop and then restart. In order for the restart to work, the Server Monitor must be enabled. To enable the Server Monitor, click Options on the left hand side of the Enterprise Server Administration screen and select the Monitor tab.

Use "Force stop" option

Check this if you want to perform a forced shutdown of the server.

Mark server "Stopped"

Check this if you know that all the processes for this server are already stopped.

Security settings

This section indicates whether the server is using its own security settings and associated security manager list, or the Default ES Security configuration settings, which can be shared by multiple servers.

Where it is using its own security settings, the security managers in its security manager list are displayed.

Stop processes as

This specifies the operating system account used to stop the Enterprise Server processes. You can choose to use the currently logged-on user (that is, the user account under which Directory Server is running), or you can specify the username and password for an alternative user.

Use Enterprise Server credentials of

When an enterprise server stops, it connects to Directory Server to update status information. To do this, it requires Directory Server user credentials (that is, credentials that Directory Server will verify and authorize). In order to update the Directory Server information, this user must be granted modify permission on the appropriate enterprise server resource within Directory Server.

The process of stopping the server also requires user credentials that the enterprise server will verify and authorize. In order to run the command used to stop the enterprise server, the user must have Alter permissions on the casstop resource within the OPERCMDS resource class.

It is important to note that the enterprise server is a separate security domain from the Directory Server. For example, it may be using different security configuration and different security managers.

You can specify that startup should use built-in default users or the credentials with which you are currently logged on to Enterprise Server Administration. Alternatively, you can specify a different username and password.

If you use the currently logged on user, or specify alternative user credentials, you must ensure that the user is present in both the Directory Server and the enterprise server security domains. Within the Directory Server domain, the user must have modify permission on the appropriate enterprise server resource within the Servers resource class. Within the enterprise server security domain, the user must have alter permissions on the casstop resource within the OPERCMDS resource class.

Parent topic: Enterprise Server Administration Home Page


Edit Server Instance Properties

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:
Changing the properties of a registered enterprise server instance may cause application connection errors and loss of data.
  • Server Instance Properties: General
  • Server Instance Properties: XA Resources
  • Server Instance Properties: Scripts
  • Server Instance Properties: Permissions
  • Server Instance Control
  • Server Instance Diagnostics
  • Server Instance Properties: Security
  • Enterprise Server Monitor and Control (ESMAC)
Parent topic: Enterprise Server Administration Console Help Pages


Server Instance Properties: General

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change the basic configurable attributes of an enterprise server instance.

To access this page:

  1. On the server instance screen, select the Server > Properties > General tabs.
CAUTION:
Changing the properties of a registered enterprise server instance may cause application connection errors and loss of data.
Name

Specify the unique name of the server, up to 8 characters. You can change the name only if the server has the status "Stopped". You cannot include angle brackets (<>) or ampersands (&) in the name.

System Directory

Specify the location for system work files output by the Enterprise Server, such as the console log, and trace and dump diagnostics files. This directory cannot be shared between Enterprise Servers. The default is /var/mfcobol/es/es-name (where es-name is the name of the enterprise server).

If you specify a directory in this field, that directory must exist; Enterprise Server does not create it for you.

Working Mode

Shows whether this Enterprise Server is to run 32-bit or 64-bit applications.

A 32-bit working mode server can run only 32-bit applications. A 64-bit working mode server can run only 64-bit applications.

You cannot change the working mode of the server once it has been created; you can however, change the mode when you copy or import a server.

Startup Options

Use these fields to specify the server configuration you want when the server first starts up. Any changes you make to these fields while a server is running do not take effect until the next time you start the server.

Shared Memory Pages

Specify the number of shared pages in memory to be reserved for all the processes that run in the Directory Server. Each page is 4 KB long.

Service Execution Processes

Specify the number of service execution processes that are to be started at server initialization.

Shared Memory Cushion

Specify the number of 4KB pages that should be reserved from the shared memory pages to allow the server to continue processing when the shared memory allocation is too small for the operational requirements of the server. The range is 1 through the number of shared memory pages.

Requested Licenses

Specify the number of licenses this enterprise server requires.

Show Local Console

Check this if you want to see a text window containing enterprise server messages while the server is running. the messages are written to a file called console.log, in the directory specified in System Directory. You can see the text window only on the machine running the enterprise server. The system messages are also available on the Enterprise Server Console page.

Allow Dynamic Debugging

Check this if you want to use a local or remote IDE to debug applications running in this enterprise server.

Start on System Start

Check this if you want to start the ES server when the MF Directory Server process is started. The MF Directory Server process (mfds) is usually started at system startup (e.g. on Windows it is registered as a system service by default). Typical usage is to ensure a set of ES servers are re-started automatically if a machine is re-booted. If security is enabled and the default credentials are disabled, ensure valid credentials are specified in the server "Security" properties "Automated Execution Control Enterprise Server Credentials" section.

64-Bit Working Mode

This box is for information only and will be checked if the server has a working mode of 64-bit.

Purge Old Logs

Check this if you want to remove existing console.nnn backups.

Console Log Size

Specify the maximum size of the console.log. Once this size is reached, it will be backed up as console.nnn (with nnn being incremented with each new backup) and subsequent messages will be logged to a new console.log. If set to 0, a single console.log will be created (if one already exists on startup, this will be backed up as console.bak).

Configuration Information

Specify textual configuration information that determines the startup and run-time behaviour of the server. Optional. Prefix comments with the number sign (#).

Description

Specify a text description of the server, for example, its purpose and owner. Optional.

Export

Click this to export information about this server and the objects it contains in a specified location.

Copy

Click this to create a new server that is identical to this server apart from its name.

Delete

Click this to delete this server.

Validate

Click this to generate a Validation report for this server. The Validation report informs you of any server configuration errors.

Parent topic: Edit Server Instance Properties


Server Instance Properties: XA Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the external resource managers registered with the currently selected server. From this page you can also:

  • Edit the resource manager definition
  • Add a new resource manager

To access this page:

  1. On the server instance screen, select the Server > Properties > XA Resources tabs.
ID

Shows the resource manager ID, used internally to identify a particular XA configuration.

Name

Shows the name by which the resource manager is known.

Module

Shows the location of the executable file (.dll on Windows),(.sl on HP-UX PA-RISC, .so on other UNIX platforms) that contains the entry point that returns the xa_switch_t structure to the enterprise server.

Open string

Shows the string that is passed to the resource manager on the xa_open() call. It usually contains at least the database name, and the user ID and password for connecting to the database. The contents of this string are database-specific.

Close string

Shows the string that is passed to the resource manager on the xa_close() call.

Description

Shows an optional text description of the resource manager definition.

Add

Click this to add a resource manager.

Enabled

Shows the status of the resource manager. A tick indicates that it is enabled.

  • Server Instance Properties: Add XA Resource
Parent topic: Edit Server Instance Properties


Server Instance Properties: Add XA Resource

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to specify the details of an external resource manager that the server needs to communicate with on behalf of container-managed applications.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > XA Resources tabs.
  3. Select the XA resource to display.
ID
Specify a resource manager ID, used internally to identify a particular XA configuration. This must be unique within the enterprise server. Mandatory.
Name
Specify the name by which the resource manager is known. It should match the name returned in the name field of the xa_switch_t structure. Mandatory.
Module
Specify the location of the executable file (.dll on Windows, .sl on HP-UX PA-RISC, and .so on other UNIX platforms) that contains the entry point that returns the xa_switch_t structure to the enterprise server. Mandatory.
Open string
Specify the string that is passed to the resource manager on the xa_open() call. It usually contains at least the database name, and the user ID and password for connecting to the database. The contents of this string are database-specific.

Where the resource manager supports dynamic registration, and the database vendor requires the name of the module that provides the ax_reg function, you should specify casaxlib.

Close string
The string that is passed to the resource manager on the xa_close() call. To find out whether or not you need to supply Close string, see your database vendor's documentation.
Description
Specify an optional text description of the resource manager definition.
Enabled
Check this to enable the resource manager. It is checked by default.
Parent topic: Server Instance Properties: XA Resources


Server Instance Properties: Scripts

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to edit advanced attributes of an enterprise server.

To access this page:

  1. On the server instance screen, select the Server > Properties > Scripts tabs.
ES Start Script

Specify a script to be executed to start the enterprise server. This will override the casstart command that is executed when you start an enterprise server. It is used only if you check Enabled (start script).

Enabled(start script)

Check this to enable the ES Start Script.

ES Stop Script

Specify a script to be executed to stop the enterprise server. This will override the casstop command that is executed when you stop an enterprise server. It is used only if you check Enabled (stop script).

Enabled(stop script)

Check this to enable the ES Stop Script.

On server not responding after n connection attempts

Specify the number of reconnection attempts that you want to take place before taking the action in the small entry field; the default is 1. Specify a script to be executed when the server has failed to respond to the server monitor the number of times specified in the large entry field. It is used only if you check Enabled (non-response script).

Enabled (non-response script)

Check this to enable the non-response script.

Process User ID

UNIX only. Specify a user ID to be attached to all processes started for this enterprise server, including the server itself. If you do not specify a Process User ID, the value set in Default Process User ID on the Configure Options page is used, if there is one. Otherwise, all processes run as user root, which can create problems with security and access to files. You can specify either a numeric user ID or a username.

Parent topic: Edit Server Instance Properties


Server Instance Properties: Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to specify the permissions of user groups for this enterprise server.

To access this page:

  1. On the server instance screen, select the Server > Properties > Scripts tabs.
Select

Choose group for which you wish to set permissions. Those groups that have already been granted explicit permissions on this enterprise server are marked with an asterisk.

Settings

Check each permission that you want to grant. To grant all permissions, click Allow All.

The permissions are displayed in an inverted tree structure. Those on lower branches include the permissions on the branches from which they descend. For example, the permission to restore a repository includes the permission to import a repository. Therefore, restore is shown as a descendant of import.

When you grant a particular permission, any permissions that it includes are automatically granted. Hence, when you check the Restore Repository permission, the Import Repository permission is automatically checked as well.

Where a check box for a permission is greyed out, it indicates that the permission is included by other permissions that have been granted to the group. To revoke a permission that is included by others, you must first revoke those other permissions.

Parent topic: Edit Server Instance Properties


Server Instance Control

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to monitor an enterprise server instance's processes, and to access the Enterprise Server Monitor and Control (ESMAC) user interface.

To access this page:

  1. On the server instance screen, select the Server > Control tabs.
  • Server Instance Control Settings
Parent topic: Edit Server Instance Properties


Server Instance Control Settings

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view and change detailed status information for a running an Enterprise Server instance, and to access ESMAC.

To access this page:

  1. On the server instance screen, select the Server > Control tabs.
ES Monitor and Control

Click this to go to Enterprise Server Monitor and Control (ESMAC), which provides a range of monitoring and control facilities for enterprise servers.

Service execution processes

Shows a list of all the service execution processes running on this enterprise server..

Count

Shows a sequence number for the service execution process.

Type
Shows the type of service execution process. The possible values are:
Debug
A service execution process that is being used to debug a service. This service execution process must have been started from the command line.
Normal
A normal service execution process started from the Home page of Server Administration.
Transient
A service execution process that is executing a service which has corrupted the application container, or a service that is responding to a long-running Java stateful session bean. The transient service execution process will terminate when the current service is complete, and be replaced by a new service execution process.
PID

Shows the process identifier of the service execution process. You can use this for tracking and debugging purposes.

TR Count

Shows the number of transactions this service execution process has handled since the server was started.

State
Shows what state the server is in. The possible values are:
Idle
The server is idle and waiting for client requests.
Running
The server is busy, that is, one of the services is currently processing a client request.
Executing

Shows the name of the service that is currently being executed.

Start Time

Shows the time that the current transaction started. This time is local to the machine where the Directory Server is running.

Local Time

Shows the current time. This time is local to the machine where the Directory Server is running.

Duration

Shows how long the current transaction has been running.

Auxiliary processes

Shows a list of all the auxiliary processes running on this enterprise server. Auxiliary processes are system processes that support the activity of the enterprise server.

Type (auxiliary processes)

Shows the type of auxiliary process.

PID (auxiliary processes)

Shows the process identifier of the auxiliary process. You can use this for tracking and debugging purposes.

Requested service execution processes

Specify a new number of service execution processes.

Allocated licenses

Shows the number of licenses allocated to this enterprise server. Can display "Unlimited" if an unlmited number of licenses were allocated.

Requested licenses

Specify a new number of licenses required for this server. You cannot specify a new number of licenses if Allocated licenses is set to "Unlimited".

Update

Click this to update the number of service execution processes or licenses available for this server. When you change the number of service execution processes, the server takes about 20 seconds to start the new processes or shut down existing processes. When you change the number of licenses, extra licenses are granted or refused immediately, and any licenses not required are returned to the pool of unused licenses. When the server is restarted it will use the number of service execution processes and the number of licenses configured in the Edit Server page.

Stop Server

Click this to stop the server.

The server begins to shut down and you are returned to the Home page.

Parent topic: Server Instance Control


Server Instance Diagnostics

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change the basic configurable attributes of an enterprise server instance.

To access this page:

  1. On the Edit screen, select the Diagnostics tab.
CAUTION:
Changing the properties of a registered enterprise server instance may cause application connection errors and loss of data.
  • Server Instance Diagnostics: Trace
  • Server Instance Diagnostics: Dump
  • Server Instance Diagnostics: ES Console
  • Server Instance Diagnostics: CS Console
Parent topic: Edit Server Instance Properties


Server Instance Diagnostics: Trace

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change the trace attributes of a server.

CAUTION:
Changing the properties of a registered server may cause application connection errors and loss of data.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Diagnostics > Trace tabs.
Trace Table Size

Specify the number of entries the trace buffer can hold before it wraps back to the start. (The trace buffer is also written to disk at this point if you checked Auxiliary Trace Active.) A value of 2 means that there is space for only one entry, and if you checked Auxiliary Trace Active each entry is written straight out to disk. Each entry is 24 bytes long.

Local Trace Size

Specify the number of entries the local trace table can hold before it wraps back to the start. A value of 0 (zero) means that no local trace table is allocated. Each service execution process has its own local trace table. Each entry is 24 bytes long.

Maximum Diagnostics File Size

Specify the maximum size of the auxiliary trace and dump file in kilobytes. A value of 0 (zero) means that there is no maximum size.

Cold Start Diagnostics File

Check this to indicate that the auxiliary trace and dump files are to be deleted when the server starts.

Dump on System Abend

Check this to indicate that the server should produce a dump if one of its own processes, such as a service execution process, terminates abnormally. The dump information can help you to determine the cause of the abnormal termination

Auxiliary Trace Active

Check this to indicate that trace records are to be flushed to disk before the trace table is overwritten. You should do this only if you have adequate disk space available, since the file can become very big very quickly. If you have a high-activity system use this field in conjunction with Maximum Diagnostics File Size to limit the disk usage. Writing out to a file also degrades performance.

Trace Flags

Use these flags to control what information is written to the trace file for this server. Any changes you make to these fields while a server is running take effect immediately.

Task Control

Check this to indicate that the server is to trace its task control component.

Storage Control

Check this to indicate that the server is to trace its storage control component.

Table Management

Check this to indicate that the server is to trace its table management component.

Application Container

Check this to indicate that the server is to trace its application container component.

Request Handler

Check this to indicate that the server is to trace its request handler component.

RM Interface

Check this to indicate that the server is to trace its resource manager interface component.

Communications

Check this to indicate that the server is to trace its communications component.

Exit

Check this to indicate that the server is to trace user and system exits.

Parent topic: Server Instance Diagnostics


Server Instance Diagnostics: Dump

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of diagnostic dumps created for this server.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Diagnostics > Dump tabs.
Note: If no diagnostic dumps have been created, this list is empty, and instead you see some text explaining this and the Create Dump button.
Show

Click this to view the dump on this row.

Create Dump

Click this to create a diagnostic dump for this server.

Parent topic: Server Instance Diagnostics


Server Instance Diagnostics: ES Console

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view the Enterprise Server console log for this enterprise server instance.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Diagnostics > ES Console tabs.
Note: If the enterprise server is not running, you see the message: "No live console data returned."
Show Entries

Click the radio button to the left of this control if you want to view a subset of the entries. Then specify the start and end of the subset in the two entry fields to the right. Click Refresh to view the specified subset.

Show Last

Click this if you want to view a subset of the entries at the end of the log. Then enter the number of entries you want to view in the entry field to the right. The default is that the last 10 lines are shown. Click Refresh to view the specified subset.

Entry

Shows the number of the event. Events are numbered in chronological order, with the most recent last.

Event

Shows a description of the event. Each description starts with the date and time it occurred and the name of the enterprise server.

Show Entire Log

Click this if you want to view the entire log. It should open in whatever application your browser is configured to use for text files.

Historical data available

If the status of the server is anything other than "Started", and the Directory Server is running on your machine, shows the location on your machine of the most recent console log for the server. If you click the right-pointing arrow at the end of the location, the file should open in whatever application your browser is configured to use for text files. If the file fails to open, you can go to the location and open it from there.

Parent topic: Server Instance Diagnostics


Server Instance Diagnostics: CS Console

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view the communications processes console log for this enterprise server.

Note: If the enterprise server is not running, you see the message: "No live console data returned."

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Diagnostics > CS Console tabs.
Show Entries

Click the radio button to the left of this control if you want to view a subset of the entries. Then specify the start and end of the subset in the two entry fields to the right. Click Refresh to view the specified subset.

Show Last

Click this if you want to view a subset of the entries at the end of the log. Then enter the number of entries you want to view in the entry field to the right. The default is that the last 10 lines are shown. Click Refresh to view the specified subset.

Entry

Shows the number of the event. Events are numbered in chronological order, with the most recent last.

Event

Shows a description of the event. Each description starts with the date and time it occurred.

Show Entire Log

Click this if you want to view the entire log. It should open in another browser window.

Historical data available

If the status of the server is anything other than "Started", and the Directory Server is running on your machine, shows the location on your machine of the most recent comms console log for the server. If you click the right-pointing arrow at the end of the location, the file should open in another browser window. If the file fails to open, you can go to the location and open it from there.

Parent topic: Server Instance Diagnostics


Server Instance Properties: Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to define the security settings to be used with this enterprise server.

Use default Security Configuration

Check this if you want to use your default security settings for this enterprise server. To define the default settings, click Security on the menu on the left hand side, and then click Security > Default Security Configuration.

Restrict user access

Check this to cause all access to the enterprise server through Enterprise Server Administration to be checked by the security managers specified in the Security Manager Priority List.

Verify against all Security Managers

Set this if you want each security query to be checked by all entries on the Security Manager Priority List.

If this is not set, the entries will be queried in the order that they appear on the Priority List until one gives a response of Allow, Deny, or Fail (equivalent to Deny). This response will then be used to decide what action should be taken.

If this field is set, all entries on the list will be queried, and if any returns a Deny or Fail, the access request will be denied. If there are no Deny or Fail responses and at least one of the entries on the list gives Allow as its response, the request will be allowed.

If a security manager does not have a rule for the resource or user specified in the request, it gives a response of Unknown. Whatever the setting of the Verify against all Security Managers field, if all of the entries on the priority list respond with Unknown, the request will be denied unless you have checked Allow unknown resources or Allow unknown users.

Allow unknown resources

Check this if you want the security facility to permit access to any unknown resource; that is, any resource for which all entries on the priority list return Unknown.

You might use this in circumstances where you only want to restrict access to some resources.

Allow unknown users

Check this if you want to allow unknown users to log in.

Use all groups

Check this if a user requesting authorization is to have the permissions of every group to which he or she belongs.

Uncheck this if the user is to have only the permissions of the group specified in the initial security API call that requested verification (authentication) of the user's credentials. Where no group is specified in the verify call, a default group is used.

Cache limit:

Enter the maximum size in kilobytes that enterprise server's security facility can use for caching the results of security queries.

Cache TTL:

Enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

Create audit events

Check this to enable the enterprise server to generate security audit events. These events can be captured and logged by the Audit Facility.

Configuration Information
Enter any security configuration information in this area.
Automated Execution Control Enterprise Server Credentials:
Enter the credentials to use for server start (user ID and password) to be used when the server instance is set to start when the MFDS process starts. This could be after a system re-start, or when a server is stopped from the user interface and the Restart option is selected.
ES Security Manager Priority List

This is the list of security manager (taken from the available pool) that the enterprise server can use to perform security queries.

Note: Security managers are queried in the order that they appear in the list. If the Verify against all Security Managers checkbox is not checked, the first manager in the list that responds with a definite answer will determine the result of a security query. See the text for Verify against all Security Managers for more details.

Use the up and down arrows to reposition the selected entry.

Select
Use this to select a security manager for removal or for moving to a different position in the list.
Name

This column indicates the name that used to identify a security manager.

Module

This column indicates the module used by a security manager to access an external security manager or to implement the security rules.

Description

The description column indicates the description for a security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Add

Click this to add a security manager from the pool of available managers.

Remove

Click this to remove the currently selected security manager from this list.

Note: The manager is only removed from this list, not from the available pool of managers.
Parent topic: Edit Server Instance Properties


Enterprise Server Monitor and Control (ESMAC)

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use ESMAC to change the basic configurable attributes of an enterprise server instance.

To access ESMAC:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Control tabs.
  3. On the Control page, click ES Monitor & Control.
  • Enterprise Server Monitor and Control - S2 Sidebar Help
  • Server
  • Monitor (1, 15)
  • HSF
  • Control
  • SEPs
    Use this page to view information about the service execution processes (SEPs) on the current server.
  • Clients
  • Diagnostics
  • Resources
  • Users
  • Env.Vars.
  • Dyn-Dbg.
  • System Sign On
Parent topic: Edit Server Instance Properties


Enterprise Server Monitor and Control - S2 Sidebar Help

Enterprise Server Monitor and Control enables you to monitor and control servers, services, packages and handlers on your Enterprise Server. The sidebar menu enables you access to these functions. When you click a button in the sidebar, the body of the page changes, providing information, or controls which you can use to modify settings. For help on the body of the page, click Help, Body.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Home

Click this to return to the Enterprise Server Administration home page.

Server

Click this to display information about the current server.

Monitor 1, 15

Click Monitor 1 to display information about tasks, collected at one minute intervals. Click Monitor 15 to display information about tasks, collected at 15 minute intervals.

Control

Click this to view and change control information for this server.

SEPs

Click this to view information about the SEPs (service execution processes) running on this server.

Clients

Click this to view information about the clients using this server.

Diagnostics

Click Display to view the console log, or a dump or trace data set. To select the diagnostic information to view, click:

  • Log - displays the console log. The buttons A, B and C/x have no effect with this button.
  • Dump - displays the dump data set specified by the button A, B or C/x. If you select C/x, the X dump data set is displayed.
  • Trace - displays the trace data set specified by the button A, B or C/x. If you select C/x, the in-memory trace table is displayed.
  • Blocks - specifies the number of blocks of diagnostic information to display.
Reply

Click this to view the list of current outstanding replies to ACCEPT FROM CONSOLE statements. You can see this button only if there is at least one outstanding reply.

Resources

Use the buttons in this group to:

  • View the services, packages and handlers available on this server.
  • View and maintain all active resource tables for this server.
  • View and maintain all resource tables for this server.

To access the relevant pages, click the dropdown box. You can choose an item from the list. When you choose an item, extra buttons are displayed that enable you to display the information required. You can select:

  • Services - when you select this, you can click:
    • Services - to view the services available on this server.
    • Package - to view the implementation packages available on this server.
    • Handlers - to view the request handlers available on this server.
Users

Click this to view the users able to use ESMAC.

Env. Vars.

Click this to view the environment variables for this server.

Dyn Debug
Displays the status of dynamic debugging with details of in-force debug criteria.
Chg. User.

Click this to view the System Sign On page, which enables you to sign on as another user, or to change your password.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


Server

Use this page to view system information for the server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Times

Shows the date and time at which the current server was started, and the number of days, hours, minutes and seconds that have passed since the server was started.

Counts

Shows the following information:

  • Transactions - the number of transactions that have occurred since the server was started.
  • Dumps - the number of dumps generated since the server was started.
  • Per hour - the number of transactions per hour, based on the number of transactions shown in Transactions.
  • Trace Blocks - the number of trace blocks generated since the server was started.
  • Active Clients - the number of clients that have been active since the server was started.
  • Limit - the number of concurrent client licenses allowed.
Sizes

Shows the following information:

  • Max Tasks - the maximum number of tasks that can run concurrently on this server. A task handles a process such as a SOAP service, and so on.
  • HTTP Out - the size of the data blocks passed across shared memory for HTTP output.
  • Diagnostics Size - the maximum size of a diagnostic data set. When this size is exceeded, the alternate (A or B) data set is used (and any data in that data set is overwritten). A value of 0 (zero) means that there is no maximum size.
  • ID Timeout - the global user ID timeout specified. If no ID timeout ha been defined, this field is blank.
  • Shared Memory - the number of shared pages in memory reserved for all the processes that run in the enterprise server. Each page is 4 KB long.
  • SM Total - the amount of shared memory available to this server, shown in kilobytes.
  • SM Cushion - the number of kilobytes reserved from the shared memory pages to enable the server to continue processing when the shared memory allocation is too small for the operational requirements of the server.
  • SM Free - the amount of shared memory currently free, shown in kilobytes.
States

Shows the following information:

  • Working Mode - the current working bit mode of the server.
  • Dump - shows which data set is currently set to receive dump information, which can be A or B.

    You can set the data set to be used for dump information on the Control page, which can be displayed by clicking Control.

  • Dump on Abend - the dump state. The dump state can be:
    • Sys: No Tran: No
    • Sys: Yes Tran: No
    • Sys: No Tran: Yes
    • Sys: Yes Tran: Yes

    where Sys indicates a system dump, and Tran indicates a transaction dump.

    You can set the dump state on the Control page, which can be displayed by clicking Control.

  • Trace - shows which data set is currently set to receive trace information, which can be A or B.

    You can set the data set to be used for trace information on the Control page, which can be displayed by clicking Control.

  • Active trace - indicates whether the in-memory trace is currently being recorded to the active auxiliary diagnostic data set.

    You can switch the active trace on and off on the Control page, which can be displayed by clicking Control.

Activity

Contains the following information:

  • The time at which sampling of activity was started. The time is shown in 24-hour format. The duration of sampling is 15 minutes. To see the latest activity statistics for this 15-minute period, click Refresh.
  • Average latency (100/sec) - The average latency for transactions on this server. This is shown in hundredths of a second, and as a graphical representation in yellow.
  • Average tasks (100/sec) - The average time taken to complete a task on this server. This is shown in hundredths of a second, and as graphical representation in blue.
  • Task/sec - The average number of tasks completed per second on this server. This is shown as a number, and as a graphical representation in green.
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Monitor (1, 15)

Use this page to view information on transactions that have occurred in the last n minutes, where n is 1 or 15. The display is cumulative, showing activity in n-minute intervals over the last half-an-hour for Monitor (1 minute intervals), and over the last 8 hours for Monitor (15 minute intervals).

Restriction: This topic applies only when the Enterprise Server feature is enabled.
hh:mm

Shows the time, in 24-hour format, at which the last statistics collection period ended.

The rest of the row shows:

  • The average latency for a transaction. This is shown as a figure in hundredths of a second, and as a graphical representation in yellow.
  • The average time taken to complete a task. This is shown as a figure in hundredths of a second, and as a graphical representation in blue.
  • The task count - the number of tasks completed within the one-minute interval. This is shown as a figure, and as a graphical representation in green.
Parent topic: Enterprise Server Monitor and Control (ESMAC)


HSF

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • HSF (summary)
  • HSF (transaction name)
Parent topic: Enterprise Server Monitor and Control (ESMAC)


HSF (summary)

Use this page to view summary HSF information for this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This shows the period of time (displayed in minutes and seconds next to Historical Statistics) between the earliest records displayed and the current time. Records older than one hour are deleted. The following information is shown for each transaction:

Average Latency
The average time, in hundredths of a second, between Enterprise Server receiving the requests and the tasks beginning to run.
Average Response Time
The average time, in hundredths of a second, that the tasks ran for (not including latency time).
Count
How many times the task has run.
Parent topic: HSF


HSF (transaction name)

Use this page to view detailed HSF information for this transaction.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Latency+Resp
The sum of latency and response time averages.
Transaction
The name of task:
  • for Web services, the service name
Process ID
Process ID of the SEP which ran the task.
Task Number
A unique task number.
Date
The date the task started to run, in the format yyyymmdd.
Time
The time the task started to run, in the format hhmmsscc.
Parent topic: HSF


Control

Use this page to view and change control information for this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Apply

Click this to save changes you have made to the page and refresh the page. This button is displayed only if you have the required permissions.

General
SEPS

Shows the number of concurrent service execution processes currently supported by this server. You can change the number by entering a value in the field.

Admin
The number of Admin SEPs defined
HTTP Out

Shows the size of the data blocks passed across shared memory for HTTP output. You can change the HTTP size by entering a value in the HTTP Size field.

Timeouts
ID

Shows the time in minutes that the system will allow an ESMAC session to remain idle before logging off the user. At system startup, this is initialized to the value specified in the System Initialization Table. A value of 0 indicates that there is no timeout. Please note that if you change the value, the change will not be saved at system shutdown.

Runaway

Shows the maximum continuous period of time in seconds that the region will allow a transaction to run without making an API call. When this value is exceeded, the transaction is abended. At system startup, this is initialized to the value specified in the System Initialization Table. A value of 0 indicates that there is no timeout. Please note that if you change the value, the change will not be saved at system shutdown. Note also that you can override this value for an individual transaction through the relevant Program Control Table entry.

Deadlock

Shows the maximum time in seconds that the region will permit an application to wait for a resource that has been locked by another process. At system startup, this is initialized to the value specified in the System Initialization Table. A value of 0 indicates that there is no timeout. Please note that if you change the value, the change will not be saved at system shutdown. Note also that you can override this value for an individual transaction through the relevant Program Control Table entry.

Diagnostics
Size

Shows the maximum size of the auxiliary trace and dump file in kilobytes. A value of 0 (zero) means that there is no maximum size. You can change the size by entering a value, in kilobytes, in the Diagnostic Size field. The maximum size you can enter in this field is 999999 kilobytes.

Dump

Shows the current data set used for dump information.

Switch

Click this to switch between the A and B data sets that are used to store dump information.

Dump

Click this to initiate a dump. Dump information is stored in the data set identified by Active Dump DS. If you do not initiate a dump using Dump, dumps occur when the system and/or transaction abends. A dump will occur on an abend only if Sys and/or Tran is checked in the Dump on Abend group.

Countn

Shows the number of dumps (n) that have occurred.

Trace

Shows the current data set used for trace information.

Switch

Click this to switch between A and B data sets used to store trace information.

Aux, active

If checked, the in-memory trace data is transferred to the auxiliary (diagnostic) data set at the roll-over of the system trace table.

Blocks

Shows the number of blocks of trace information captured.

Dump on ABEND
Debugger
Check this to enable dynamic debugging.
HSF Data
Enable collection of Historical Statistics Facility (HSF) records
This switches on HSF processing.
Write to disk
Enables writing of HSF records to comma-separated files. These are called cashsf-a.csv and cashsf-b.csv, and are written to the system directory. Only one file is written to at any one time - this is called the active file.

You write to the active file until you click the ESMAC Switch button or when the active file reaches the maximum size, at which point the alternate file becomes active. If the alternate file already exists it will be backed up with the name cashsf.nnn where nnn is the number of the backup. When you start an enterprise server, cashsf-a.csv is always set as the active file, and if it already exists it is backed up.

Backup extensions are numbered from .001 up to .999. When a backup with extension .999 exists then the next backup will be created as cashsf.001. If cashsf.001 already exists then it will be overwritten.

Maximum HSF file size (KB)
If you have selected Write to disk, this is the size in kilobytes the .csv file will reach before Enterprise Server switches to the alternate .csv file. A value 0 selects the maximum size possible (4 Gb).
Number of records displayed by ES Monitor & Control
The number of HSF records that Enterprise Server will hold in memory. These records can be viewed by clicking on the HSF button in ESMAC while the server is running. When this number is reached, older records will be deleted when a new one is created. Records older than one hour are deleted too.
The minimum value is 0 (no HSF data displays in ESMAC), the maximum is 4096.

Clicking the Switch button will switch collection to the alternate .csv file before the active file has reached the maximum size.

Trace Points

Shows the currently set trace points. The trace points shown are those that have been set by the SIT. You can change individual trace points by checking the check box next to each trace point, or you can use all to change all the settings at once. This overrides the trace points set by the SIT. Any changes you make are effective immediately you click Apply. The changes are lost, however, the next time the server is initialized.

all
Choose a setting to apply to all the trace points:
  • On - enables all the trace points
  • Off - disables all the trace points
Attention: When you set all the trace points on at once, the trace points CCI, fh and fh-enable are unaffected. This is because these trace points should be used only when advised by Micro Focus.
Server
lock-data
Check this to trace lock management for non-threaded processes.
tsc
Check this to trace calls to the castsc process.
sql-api
Not used.
tsc-data
Check this to trace the data in calls to the castsc process.
fh
Do not check this unless advised by Micro Focus.
tsc-thread
Check this to trace thread processing and lock management in the castsc process.
fh-enable
Do not check this unless advised by Micro Focus.
trd
Check this to trace thread processing in all threaded processes.
xfp
Check this to trace data in transformer processing.
trd-enq
Check this to trace processes and data in transformer processing.
xfp-all
Check this to trace data and processes in transformer processing.
saf(security)
Check this trace System Authorization Facility (SAF) calls.
trd-stg
Check this to trace memory management in threaded processes.
xfp-data
Check this to trace data in transformer processing for threaded processes.
Communications
cci
Do not check this unless advised by Micro Focus.
data
Check this to trace basic data in the communication module.
mfcs-cg
Check this to trace Micro Focus Communications Server (MFCS) requests
common
Check this to trace thread processing in the communications module.
data-all
Check this to trace extended data in communication module.
cg-thread
Check this to trace lock management in the communications module.
Memory Strategy
Use this to control the frequency and type of runtime memory validation, as well as specifying the processes to which these settings apply.
Debug SEP
Start
Starts a debug SEP. A value of "Any" indicates that any transaction can be debugged in this SEP.
Transaction
Indicates the only transaction to be debugged in this SEP.

If terminals are connected, the additional option Terminal enables you to debug only those transactions initiated from the selected terminal.

Shutdown
Click this to shut down the current server. You restart the server using Enterprise Server Administration.
Dump
A system dump is taken when the server shuts down.
Immediate

Check this to force an immediate shutdown when you click Shutdown. If you force an immediate shutdown, you will see "The page cannot be displayed" error, as there is no longer a server to connect to.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


SEPs

Use this page to view information about the service execution processes (SEPs) on the current server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The page is divided into five sections:

  • Standard - SEPs executing your transactions.
  • Auxiliary - processes run by the server that provide auxiliary services to the SEPs.
  • Debug - processes handling debug requests. You see this section only if there are debug processes executing.
  • Transient - long running processes. Once the process has completed, the SEP is removed from the list.
Trace

Click this to view a system trace for the SEP.

Kill

Click this to kill the SEP while a task is running.

Stop

Click this to stop the SEP when the current task completes.

Process ID, Start Time, Service/TranID

This column shows the process ID, the time at which the service was started, and the service or transaction ID (where available).

Type, Duration

This column shows the type of service and the amount of time the service has been running. The type can be:

  • SEP - service execution process
  • CAS Manager - An enterprise server management service
  • JCP - journal control program
  • TDP - extra-partition transient data program
  • Fileshare - A Fileshare service
Task Number, Client, Function

This column shows the task number for the service, the process ID (pid) of the client using this server, and the function. You can see which clients are associated with a process ID by displaying the Clients page; click Clients to do this.

Tran. count, Wait ID/Duration, User ID

This column shows the number of transactions performed by this SEP, the wait ID and user ID. The wait ID indicates, for suspended services, the ID of the process that is waiting to complete and the amount of time the process has been waiting. The user ID displays the ID of the signed-on client that is currently being processed.

Process ID, Start Time

This column shows the process ID and the time at which the service was started.

Initiator Classes, Duration

This column shows the classes that the batch initiator SEP handles and the amount of time the SEP has been running.

SYSOUT Classes, Duration

This column shows the classes that the batch printer SEP handles and the amount of time the SEP has been running.

Device

Shows the name of the printer being used.

Exit

Shows the pathname of the printer exit program that this batch printer SEP uses when it prints jobs, if any.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


Clients

Use this page to display Client information for this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Process ID

Shows the process ID of the client.

Type

Shows the type of client:

  • CCI - A client that uses CCI (Common Communications Interface) to connect to the server
  • CCI HTTP - A client that uses HTTP (Hyper Text Transmission Protocol) - such as SOAP, BINP, CGI
  • Comms Server - Client communications controller process (listener)
  • ECI - External Call Interface
  • FileShare - Traditional Fileshare2 client
  • Generic
  • Other
  • SESSION - A LU6.2-type session that is multiplexed on a link
  • Spool - System spooler client
  • SURROGATE - Surrogate for a client attached to another server
  • SURROGATE-t
  • SYSTEM - A peer server
  • UniCli - An IBM universal client
Net Name

Shows the assigned SNA network node name for that client.

User ID

Shows the user ID of the user running the client. This might be a system ID, such as HTTP Soap for system services such as the SOAP listener.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


Diagnostics

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Dump data set
  • Trace store
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Dump data set

Use this page to view dump information, contained in data set, for the transactions on this server. data set can be A, B or X.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to see detailed information for the dump selected. The detailed information includes the summary information at the end.

Sum

Click this to see summary information for the dump selected.

Level

Choose a level of trace information that you want to be included in the trace tables in the dump. The trace information includes system trace tables and local trace tables. The options are:

0 | Service start, module start, module end, service end.
1 | Enterprise server API entries and exits
2 | Subsystem trace entres
3 | All entries where it is possible to provide some formatting of the data
4 | All trace entries. This is the default.

This option affects what you see in a detailed dump, not a summary dump. Local trace tables (traces for SEPs) only have levels 0 and 1.

PID, Code (Caller)

Shows information about the dump:

  • The process ID
  • A code that helps identify the dump
  • The origin of the dump request
Date(mm/dd/yy) Time

Shows a date and time stamp for the dump. The time stamp is in hours, minutes, seconds, and hundredths of a second.

Parent topic: Diagnostics


Trace store

Use this page to view trace information contained in a dataset or in memory. store can be A or B, for the A or B datasets, or X to indicate an in-memory trace.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to see detailed information for the trace selected.

Blocks

Specify the number of blocks that you want to be included in the detailed trace information starting at the first block in this index entry. The default is the number you specified in Blocks in the Diagnostics group in the menu.

Level

Choose a level of trace information that you want to be included in the details:

0 | Service start, module start, module end, service end. This is the default.
1 | Enterprise server API entries and exits
2 | Subsystem trace entres
3 | All entries where it is possible to provide some formatting of the data
4 | All trace entries
PIDs

If you want to filter the details by process ID, check the check boxes next to the process IDS of the processes you want detailed trace information for.

Task IDs

If you want to filter the details by task ID, check the check boxes next to the task IDS of the tasks you want detailed trace information for.

Date(mm/dd/yy) Time

Shows a date and time stamp for the dump. The time stamp is in hours, minutes, seconds and hundredths of a second.

Parent topic: Diagnostics


Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Services
  • Active
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Lists of Services
  • Details of Individual Services
Parent topic: Resources


Lists of Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Services
  • Service Packages
  • Request Handlers
Parent topic: Services


Services

Use this page to view information about the services currently available on the server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to view detailed information for the service.

The rest of the information in this row shows:

  • The location of a service
  • The protocol used by the service
Show Sys Entries

Click this to view the system services.

The page expands to include all the system services currently running. You can click Details for any of these system services to get more information.

Hide Sys Entries

Click this to hide the system services.

This button is displayed only if you have previously clicked Show Sys Entries.

Parent topic: Lists of Services


Service Packages

Use this page to view information about the implementation packages available on the current server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to display detailed information for the package.

The rest of the information in this row shows the name of the implementation package.

Parent topic: Lists of Services


Request Handlers

Use this page to view information about the request handlers available on the current server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to view detailed information for the request handler.

The rest of the information in this row shows the name of the request handler.

Parent topic: Lists of Services


Details of Individual Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Service
  • Service Package
  • Request Handler
Parent topic: Services


Service

Use this page to view information about a particular service, selected from the Services page. You can also change the log status and create a new copy of the IDT.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Apply

Click this to save changes you have made to the page and refresh the page. This button is displayed only if you have permission to edit the service.

Name

Shows the service namespace.

Transaction

Shows the characteristics of the service. The characteristics relate to the commit/rollback of protected resources accessed by the service. Values can be Container Managed or Application Managed.

RTS Trace

Specifies the state of entry and exit tracing for the service:

  • None - no tracing is done
  • User - user applications are traced
  • System - the system is traced
  • Both - both applications and the system are traced
Log I/O

Shows whether, for each request for this service the request and response blocks are written to the enterprise server dump data set. If None, nothing is logged. If Dump, request and response blocks are written to the enterprise server dump data set. To set the log to None or Dump, click on the dropdown box, select the required setting, and click Change.

Only use this option if you need diagnostics, as it degrades performance.

Ref. Count

Shows the number of applications that reference this service.

Service Status

Shows the current status of the service. The possible statuses are:

  • In service - the service is available.
  • Error - an error has occurred such that it has not been possible to set the status to any other value.
  • Disabled - the service is disabled.
Parent topic: Details of Individual Services


Service Package

Use this page to view information about a particular implementation package, selected from the Service Packages page. You can also use this page to force the load of a new copy of the IDT.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Name

Shows the name of the implementation package for this service.

IDT

Shows the path of the IDT (interface definition table) for the package.

IDT Size

Shows the physical size of the specified IDT. The IDT size is shown only if the IDT is currently loaded and held in shared memory.

New Copy

Click this to force a new copy of the IDT to be loaded for the next execution of the service. If an IDT is resident (that is, in shared memory), New Copy removes it, forcing the system to reload the IDT from disk the next time a service requests it.

Module

Shows the name of the library that contains the package, if any.

Status

Shows the current status of the implementation package. The possible statuses are:

  • In service - the package is available.
  • Error - an error has occurred such that it has not been possible to set the status to any other value.
  • Disabled - the package is disabled.
Location

Shows the path where the package file is located.

Ref. Count

Shows the number of programs that have made use of this package since the server started.

Parent topic: Details of Individual Services


Request Handler

Use this page to view information about a particular request handler, selected from the Request Handlers page.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Name

Shows the name of the request handler.

Handle ID

Shows the unique ID assigned to this handler by the server.

Status

Shows the current status of the request handler:

  • In service - the request handler is available.
  • Error - an error has occurred such that it has not been possible to set the status to any other value.
  • Disabled - the request handler is disabled.
Type

Shows the type of request handler:

  • Other
  • Soap
  • CGI
  • Undefined
Location

Shows the path where the handler is located.

Ref. Count

Shows the number of programs that have made use of this handler since the server started.

Parent topic: Details of Individual Services


Active

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Lists of Active Resources
  • Details of an Active Resource
Parent topic: Resources


Lists of Active Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Locks (Active)
  • XAT (Active)
Parent topic: Active


Locks (Active)

Use this page to view the current resource locks on this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Lock Ownership
Lists the current locks.
PID

Shows the process ID (PID) of a process that has issued a lock or wishes to issue a lock.

res-ID

Shows a resource ID allocated to the locked resource for the purposes of linking the information in the Lock Ownership part of the table with the information in the Resource Details part of the table.

Type

Shows the type of lock.

State

Shows the state of the lock. Possible states are:

Controlled | The requester has control of the resource
Waiting | The requester is waiting to gain control of the resource (synchronous request)
Pending | The requester has issued the request but has continued with other work (asynchronous request)
Persistence

Shows how long the lock lasts. Possible values are:

LUW | The lock lasts until the logical unit of work ends
Task | The lock lasts until the task ends
Lock Manager | There is no implicit release of the lock.
Process | The lock lasts until the process ends
Seq
The order in which requesters are to be handled.
Resource Details
Lists the resources that are locked.
Res ID (Resource Details)

Shows a resource ID allocated to the locked resource for the purposes of linking the information in the Lock Ownership part of the table with the information in the Resource Details part of the table.

Queue

Shows the lock namespace.

Length

Length of the resource name in characters.

Resource Name

Shows the name of the resource given to it by the requester.

Parent topic: Lists of Active Resources


XAT (Active)

Use this page to view the list of XATs defined in resource groups used by the startup list name.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Details

Click this to see detailed information for the XAT in this row.

The rest of the information in this row shows:

  • The name of the XAT
  • Whether it is currently enabled or disabled
Parent topic: Lists of Active Resources


Details of an Active Resource

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • XAT
Parent topic: Active


XAT

Use this page to view the XATs (XA-compliant database tables) defined for the server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Switch Module

The location of the executable file (.dll on Windows, .sl on HP-UX PA-RISC, .so on other UNIX platforms) that contains the entry point that returns the xa_switch_t structure to the enterprise server.

Open String

The string that is passed to the resource manager on the xa_open() call. An entry in this field usually contains at least the database name, and the user ID and password for connecting to the database. The contents of this string are database-specific.

For DB2, the contents are documented in IBM's DB2 Administration Guide; for additional information see the Application Programmer's Guide.

For Oracle, see the Oracle Application Developer's Guide - Fundamentals.

Where the resource manager supports dynamic registration, and the database vendor requires the name of the module that provides the ax_reg function, you should specify casaxlib.

Close String

The string that is passed to the resource manager on the xa_close() call. To find out whether or not you need to supply Close string, see your database vendor's documentation.

Enabled

Whether this XAT resource is enabled or disabled.

Parent topic: Details of an Active Resource


Users

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Users List
Parent topic: Enterprise Server Monitor and Control (ESMAC)


Users List

Use this page to view the users defined for this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
New

Click this to create a new user.

Details

Click this to display information about a user.

The information in the rest of the row shows you the name of the user, the operator ID, and a short description of the user.

Parent topic: Users


Env.Vars.

Use this page to view information about the environment variables used by this server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Name

Lists all of the environment variables currently in use by the server.

Value

Lists the values for all of the environment variables listed in the Name column.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


Dyn-Dbg.

Use this page to view the debugging criteria for active dynamic debug sessions. You can use X to remove the entry for a particular session.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Type

The type of application or service being debugged.

Criteria

The criteria used to identify the application or service instance to debug.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


System Sign On

Use this page to sign on to the system. You can also use this page to change your password.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Sign On

Click this to sign on. You must first enter your user ID and password.

ID

Enter your user ID.

Password

Enter the password associated with your user ID.

Group
The group of which this user is a member.
New Password

If you want to create a new password for your user ID, enter it in this field. You must enter your current password in the Password field before you can change your password.

Repeat PW

Confirm your new password by re-entering it in this field.

Default

Click this to sign onto the system using the default user ID, and display the System page. Any changes you made to the page before you clicked Default are lost.

Parent topic: Enterprise Server Monitor and Control (ESMAC)


Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the communications processes and service listeners registered for the currently selected server. From this page you can also:

  • Make some specific edits to a communications process
  • Create a communications process by copying an existing one
  • Delete a communications process
  • Edit the configurable settings of a listener
  • Add a new listener

To access this page:

  1. On the server instance screen, select the Listeners tab.
Listener Display Filters

Use this group of fields to apply filters to the list of listeners so that you can just view a subset.

Note:

It is possible to specify filters such that no information is displayed.

Process

Choose an option for filtering by communications process:

All | To list all service listeners regardless of communications process
None | To list no service listeners
n | To list just the service listeners that belong to communications process n
Conversation Type (filter)

Choose an option for filtering by conversation type:

All | To list all service listeners regardless of conversation type
Custom | To list service listeners with a custom conversation type
Web Services and J2EE | To list Web Services and J2EE service listeners
Web | To list Web service listeners
Fileshare | To list Fileshare service listeners
Status

Choose an option for filtering by status:

All To list all service listeners regardless of status
status-type To list service listeners with the status status-type, where status-type can be one of:
  • Started
  • Stopped
  • Disabled
  • Blocked
  • Not Responding; this means any listener whose status is unknown because the server it is registered with is not responding to the server monitor
  • Not Started; this means any listener with a status other than Started
  • Not Stopped; this means any listener with a status other than Stopped
Auto-start

Check this to indicate that this communications process is started automatically when the enterprise server starts.

Statistics

Click this to see detailed information about the listener activity on this enterprise server. The information is shown in a new window. You can click this only if the enterprise server is started.

Change

Changes into Stop or Start when the enterprise server is started.

Stop

Click this to stop the communications process and all its listeners. You can click this only if the enterprise server is started, the communications process is started, and this communications process is not Communications Process 1.

Start

Click this to start the communications process and all its listeners. You can click this only if the enterprise server is started, the communications process is not started, and this communications process is not Communications Process 1.

Copy

Click this to create a new communications process by copying this one.

Delete

Click this to delete this communications process. If a server only has one communications process you cannot delete it.

Edit (communications process)

Click this to edit configurable settings for this communications process.

Listeners

Shows the number of listeners owned by this communications process.

Add

Click this to add a new listener.

Process ID

Shows the process ID of this communications process.

Control Channel Address

Shows the internal address used by the communications process for communicating with other components of the enterprise server. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the communications process. An asterisk (*) indicates that the address is dynamically assigned for the communications process when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the communications process when it starts.

Under the network address is the DNS-resolved TCP/IP hostname.

Status (communications process)

Shows the current status of the communications process. The possible statuses are:

Not responding | The communications process status is unknown because the server it is registered with is not responding to the server monitor.
Started | The communications process is running.
Stopped | The communications process is stopped.
Last Status Change (communications process)

Shows the time that the communications process's current status was last updated; this time is local to the machine where the Directory Server is running.

Status Log (communications process)

Shows information about the most recent event that occurred on this communications process.

Version

Shows the version string of the communications process. This consists of three elements in decreasing order of significance: major version, minor version, build version. This can be used to distinguish between communications processes of the same name.

Edit (listener)

Click this to edit configurable settings for this listener.

Name

Shows the name of the service listener.

Address

Shows the network address used by the listener to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the listener when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts.

Under the network address is the DNS-resolved TCP/IP hostname.

Status (listener)

Shows the current status of the service listener. The possible statuses are:

Blocked | The listener is started when the server starts, but it does not accept client requests.
Disabled | The listener is stopped and is therefore not available to any client
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Not responding | The listener status is unknown because the server it is registered with is not responding to the server monitor
Started | The server listener is running.
Stopped | The listener is stopped.
Start Pending | The SSL-enabled communications process is waiting for you to enter a password to give access to its private key. Less commonly, a password may also be required to give access to its certificate. To do this, click Authorize. On the page that appears in a second browser, enter the password (leave the certificate password blank unless it's required) and click Set Passphrases. Then close that browser.
Last Status Change (listener)

Shows the time that the listener's current status was last updated; this time is local to the machine where the Directory Server is running.

Status Log (listener)

Shows information about the most recent event that occurred on this listener.

Conversation Type

Shows the conversation type of the listener.

Custom Configuration Data

Shows optional textual configuration information that determines the start-up and run-time behavior of the listener. For details of the entries, see the section Configuration Information in the chapter Communications Processes and Service Listeners in your Configuration and Administration Guide.

Description

Shows an optional text description of the listener, for example, its purpose and owner.

  • Add Listener
  • Edit Listener
  • Delete Listener
  • Copy Communications Process
  • Edit Communications Process
  • Delete Communications Process
Parent topic: Enterprise Server Administration Console Help Pages


Add Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add a new service listener to the selected communications process.

To access this page:

  1. On the Listeners screen, in the Communications process area, click Edit.
Name

Specify the unique name of the new service listener, up to 255 characters in length. You cannot include angle brackets (<>) or ampersands (&) in the name.

Endpoint Protocol

Specify the communications protocol used by the listener to accept incoming client requests. TCP is the only option.

Endpoint Address

Specify the network address used by the listener to accept incoming client requests. The format is:

ip-address:port

where:

  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is the IP address of the current machine.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts.

If this network address is not unique in the repository, this may cause listener startup problems.

Secure Sockets Layer

Not currently used.

Legacy Micro Focus Application Format

Check this if you want the listener to handle non-standard TCP/IP flows, for example, for Fileshare clients.

Initial Status

Choose a status from the list. The possible statuses are:

Blocked | The listener is started when the server starts, but it does not accept client requests. One use for this status is where you want to allow requests from only one client, perhaps for debugging purposes. You could amend the client code to ignore a status of "Blocked"and allow requests through.
Disabled | The listener is not started when the server starts and is therefore not available to any client
Stopped | The listener is available but stopped. This is the default. To start a listener use the Edit Listener page. When you add a stopped listener to a server that has a status of "Started", the server will attempt to start the listener immediately. If you add a stopped listener to a server that has a status of "Stopped", when the server is started it will attempt to start the listener.
Supported Conversation Type

if you chose TCP in Endpoint Protocol, click one button to choose a conversation type:

  • Web Services / J2EE for client requests that use a conversation protocol supported by the request handlers provided by Micro Focus, MFRHBINP and MFRHSOAP.
  • Web for World Wide Web (HTTP) client requests. Enterprise Server uses a Web listener for service deployment.
  • Fileshare for Fileshare client requests.
  • Custom for other kinds of client requests. Specify the name of the connector module in the entry field next to Custom.
Configuration Information

Specify textual configuration information that determines the startup and run-time behavior of the listener. Optional. For details of the valid entries, see the section Configuration Information in the chapter Communications Processes and Service Listeners in your Configuration and Administration Guide.

Description

Specify an optional text description of the listener, for example, its purpose and owner. Optional.

Add

Click this to add the listener to the current server.

Parent topic: Listeners


Edit Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of a listener.

To access this page:

  1. On the Listeners screen, next to the listener to edit, click Edit.
Servers

Click this to return to the list of all the servers on this Directory Server, on the Home page.

Listeners

Click this to view a list of all the service listeners registered with the current server.

Services

Click this to view a list of all the services registered with the current server.

Handlers

Click this to view a list of all the request handlers registered with the current server.

Packages

Click this to view a list of all the packages registered with the current server.

Name

Specify the unique name of the listener, up to 255 characters in length. You cannot include angle brackets (<>) or ampersands (&) in the name.

Connection Endpoint

Specify the network address used by the listener to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the listener when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts.

If this network address is not unique in the repository, this may cause listener start-up problems.

Secure Sockets Layer

This is accessible if you have the Micro Focus Security Pack installed.

Legacy Micro Focus Application Format

Check this if you want the listener to handle non-standard TCP/IP flows, for example, for Fileshare clients.

Current Status

Shows the current status of the listener:

Blocked | The listener is started when the server starts, but it does not accept client requests.
Disabled | The listener is stopped and is therefore not available to any client
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Not responding | The listener status is unknown because the server it is registered with is not responding to the server monitor
Started | The server listener is running.
Stopped | The listener is stopped.
New Status

Choose a status from the list. If the status of the server is "Started", the possible listener statuses are:

Blocked | The listener is still running but will not be found by clients searching for this listener in a "Started" state. One use for this status is where you want to allow requests from only one client, perhaps for debugging purposes. You could amend the client code to ignore a "Blocked" status and allow requests through.
Disabled | The listener is stopped and will not be started.
Started | The server listener is started.
Stopped | The listener is stopped.

If the status of the server is "Stopped", the possible statuses are:

Blocked | The listener is stopped. The listener is started when the server starts, but will not be found by clients searching for this listener in a "Started" state. One use for this status is where you want to allow requests from only one client, perhaps for debugging purposes. You could amend the client code to ignore a "Blocked" status and allow requests through.
Disabled | The listener is stopped and it will not be started when the server starts.
Stopped | The listener is stopped. It will be started when the server starts.
Supported Conversation Type

Shows the conversation type of the listener.

  • MFES Requests for client requests that use a conversation protocol supported by the request handlers provided by Micro Focus, MFRHBINP and MFRHSOAP.
  • Custom for other kinds of client requests. Specify the name of the connector module in the entry field next to Custom.
Configuration Information

Specify textual configuration information that determines the start-up and run-time behavior of the listener. Optional.

Description

Specify a text description of the listener, for example, its purpose and owner. Optional.

Apply

Click this to apply your changes to the listener.

Delete

Click this to delete the listener. You cannot delete a listener if it is registered for use with a service.

Parent topic: Listeners


Delete Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete the selected listener.

To access this page:

  1. On the Listeners screen, next to the listener to edit, click Delete.
CAUTION:

Deleting a registered listener may cause application connection errors and loss of data

Name

Shows the name of the listener.

Connection Endpoint

Shows the network address used by the listener to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the server listener. An asterisk (*) indicates that the address is dynamically assigned for the listener when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts.
Current Status

Shows the current status of the service listener. The possible statuses are:

Blocked | The listener is started when the server starts, but it does not accept client requests.
Disabled | The listener is stopped and is therefore not available to any client
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Not responding | The listener status is unknown because the server it is registered with is not responding to the server monitor
Started | The server listener is running.
Stopped | The listener is stopped.
Description

Shows a text description of the listener.

Parent topic: Listeners


Copy Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to create a new communications process by copying the details of an existing communications process.

To access this page:

  1. On the Listeners screen, in the Communications process area, click Edit.
Control Channel Address

Specify the network address used by the communications process to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the communications process. An asterisk (*) indicates that the address is the IP address of the current machine.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the communications process when it starts.

If this network address is not unique in the repository, this may cause communications process startup problems.

Secure Sockets Layer

Not currently used.

Auto-start

Check this to indicate that the new communications process is started automatically when the enterprise server is started. If you copy a communications process while the enterprise server is running, and you check this, the new communications process is started immediately.

Parent topic: Listeners


Edit Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of a communications process.

To access this page:

  1. On the Listeners screen, in the Communications process area, click Edit.
Control Channel Address

Specify the network address used by the communications process to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the communications process. An asterisk (*) indicates that the address is dynamically assigned for the communications process when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the communications process when it starts.

If this network address is not unique in the repository, this may cause communications process startup problems.

Secure Sockets Layer

Not currently used.

Configuration Information

Specify textual configuration information that determines the start-up and run-time behavior of the communications process. Optional. You cannot change this if the enterprise server has a status of "Started". For details of the valid entries, see the section Configuration Information in the chapter Communications Processes and Service Listeners in your Configuration and Administration Guide.

Parent topic: Listeners


Delete Communications Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete the selected communications process.

CAUTION:

Deleting a communications process may cause application connection errors and loss of data.

Name

Shows the name of the communications process.

Address

Shows the network address used by the communications process to accept incoming client requests. The format is:

protocol:ip-address:port

where:

  • protocol is tcp.
  • ip-address is either the text host name or IP address of the communications process. An asterisk (*) indicates that the address is dynamically assigned for the communications process when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the communications process when it starts.
Listeners

Shows the number of listeners owned by the communications process.

Parent topic: Listeners


Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the services registered for the currently selected server. From this page you can also:

  • Edit the configurable settings of a service
  • Add a new service
Service Display Filters

Use this group of fields to apply filters to the list of services so that you can just view a subset.

Note:

It is possible to specify filters such that no information is displayed.

Service

Specify a service namespace to see just the details for that service namespace.

Class

Choose an option for filtering by service class:

All | To list all service namespaces regardless of service class
Some | To list those service namespaces that have a value in Service Class
None | To list those service namespaces that have no value in Service Class
Handler

Choose an option for filtering by request handler:

All | To list all service namespaces regardless of which request handler is associated with the service
Some | To list those service namespaces that have a value in Request Handler
None | To list those service namespaces that have no value in Request Handler
Package

Choose an option for filtering by implementation package:

All | To list all service namespaces regardless of which implementation package is associated with the service
Some | To list those service namespaces that have a value in Implementation Package
None | To list those service namespaces that have no value in Implementation Package
Show

Specify the number of service namespaces to show at a time. If you change this, you have to click Refresh to see the effect.

Previous

Click this to view the previous page of service namespaces. You can click this only if the number of service namespaces is greater than can be shown on one page.

Next

Click this to view the next page of service namespaces. You can click this only if the number of service namespaces is greater than can be shown on one page.

Edit

Click this to edit configurable settings for the service.

Service Namespace

Shows the service namespace. For more information about service namespace and service operation see your Configuration and Administration book.

Operation

Shows the name of the operations in the service namespace.

Service Class

Shows the class of the service. This field provides a means of grouping services, so that a client program can ask for a class of service rather than a specific named service. Service classes beginning with MF are reserved for Micro Focus use.

Search Order

Shows the search order of the service. The lower the search order, the higher the search priority where there is more than one service object of the same name in the repository.

Listeners

Lists the listeners allocated to this service. For each listener the fofllowing information is shown:

  • The communications process that it belongs to, for example CP1 (communications process 1)
  • Its name
  • Its address in both IP address and hostname formats
Request Handler

Shows the name and path of the request handler for this service.

Implementation Package

Shows the name of the implementation package for this service.

Current Status

Shows the current status of the service. The possible statuses are:

Available | The service is available.
Invalid | An error has occurred such that it has not been possible to set the status to any other value.
Disabled | The service is disabled.
Status Log

Shows information about the most recent event that occurred on this service.

Custom Configuration

Shows optional textual configuration information that determines the start-up and run-time behavior of the service. For details of the entries, see the section Configuration Information in the chapter Services, Packages and Request Handlers in your Configuration and Administration Guide.

Description

Shows an optional text description of the service.

Add

Click this to add a new service.

  • Edit Service
  • Delete Service
  • Delete Service Operation
Parent topic: Enterprise Server Administration Console Help Pages


Edit Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of a service.

CAUTION:
Changing the properties of a registered service may cause application connection errors and loss of data
Name

Specify the name of the service, up to 255 characters. You cannot include angle brackets (<>) or ampersands (&) in the name.

A service name can consist of a service namespace and an operation name, separated by a special character. The character depends on which request handler is being used, MFRHSOAP or MFRHBINP.

If there is no separating character, the name of the operation is considered to be the same as the service namespace.

If the service will be using the MFRHSOAP request handler, the text before the first pound character (#) in the name is considered to be the service namespace and the text after is considered to be the name of the operation.

If the service will be using the MFRHBINP request handler, the text before the last period character (.) in the name is considered to be the service namespace and the text after is considered to be the name of the operation.

Note: You can change the name of a service only when the server has a status of "Stopped".
Search Order

Specify the search order of the service. If more than one service object has the same name, then a program client can use Search Order to decide which service to use. The lower the search order is, the higher the search priority.

Service Class

Specify the service class of the service (optional). This field provides a means of grouping services, so that a client program can ask for a class of service rather than a specific named service. Service classes beginning with MF are reserved for Micro Focus use. Service Class can be up to 32 characters in length.

Version

Specify the version string of the service. This consists of three elements in decreasing order of significance: major version, minor version, build version. This can be used to distinguish between services of the same name or class.

Logging
Check this to request that for each request for this service the request and response blocks are written to the enterprise server dump data set. Only use this option if you need diagnostics as it degrades performance.
Restriction: This option only applies to services that represent COBOL applications that are executed by a request handler. It has no effect for services that are used only for directory lookup purposes, such as the MF JES service.
Transaction Management

Click one button to choose the type of transaction management that this service uses:

  • Application for a service in which the COBOL application manages their own transactions.
  • Container for a service in which the COBOL application leaves transaction management to the application container.

If the client is transactional, such as a J2EE transactional request, this setting is ignored and the service is forced to be container-managed. Container-managed services should not make any explicit transactional requests, for example, EXEC SQL COMMIT WORK statements.

Current Status

Shows the current status of the service. The possible statuses are:

Available | The service is available.
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Disabled | The service is disabled.
New Status

Choose a status from the list. The possible statuses are:

Available | The service is available.
Disabled | The service is disabled.
Accepting Listeners

Shows the listeners that will accept incoming client requests.

Available Listeners

Lists the listeners that are available to be allocated to this service. Click a listener to select it for adding to Accepting Listeners. A service can have more than one listener.

Remove

Click this to remove the selected listener from Accepting Listeners. There must be more than one listener in Accepting Listeners before you can click this.

Add

Click this to add the selected listener to Accepting Listeners.

Available Handlers

Lists the available request handlers. Click a request handler to select it to become the Associated Handler. You must add a listener before you can see Available Handlers and associate a handler with the service.

Select Handler

Click this to make the selected request handler the Associated Handler.

Associated Handler

Shows the request handler that is associated with this service, if any.

Available Packages

Lists the available implementation packages. Click a package to select it to become the Associated Package. You must add a listener before you can see Available Packages and associate a package with the service.

Select Package

Click this to make the selected package the Associated Package.

Associated Package

Shows the implementation package that is associated with this service, if any.

Configuration Information

Specify textual configuration information that determines the startup and run-time behavior of the service. Optional. For details of the valid entries, see the section Configuration Information in the chapter Services, Packages and Request Handlers in your Configuration and Administration Guide.

Description

Specify a text description of the service, for example, its purpose and owner. Optional.

Parent topic: Services


Delete Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete a service and all of its operations. You can also optionally delete the packages associated with the operations.

CAUTION:

Deleting registered services and packages may cause application connection errors and loss of data.

Full Name

Shows the full name of the service, consisting of service namespace, separator and operation name

Service Class

Shows the service class of the service.

Version

Shows the version string of the service. This consists of three elements in decreasing order of significance: major version, minor version, build version.

Listener

Shows the listener associated with the service operation.

Request Handler

Shows the request handler associated with the service operation.

Implementation Package

Shows the implementation package associated with the service operation.

Description (service)

Shows a text description of the service operation.

Name

Shows the name of the package associated with the service operation.

IDT

Shows the pathname of the interface definition table (IDT) associated with the service operation.

Description (package)

Shows a text description of the package.

Delete associated packages

Check this to delete the packages associated with the service.

Delete

Click this to delete this service, its operations and optionally the associated packages.

Parent topic: Services


Delete Service Operation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete an individual service operation, or a service that contains no operations.

CAUTION:

Deleting a registered service may cause application connection errors and loss of data.

Name

Shows the name of the service.

Service Class

Shows the service class of the service.

Version

Shows the version string of the service. This consists of three elements in decreasing order of significance: major version, minor version, build version.

Listener

Shows the listener associated with the service.

Current Status

Shows the current status of the service. The possible statuses are:

Available | The service is available.
Invalid | An error has occurred such that it has not been possible to set the status to any other value.
Disabled | The service is disabled.
Status Log

Shows information about the most recent event that occurred on this service.

Description

Shows a text description of the service.

Delete

Click this to delete this service.

Parent topic: Services


Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the request handlers registered for the currently selected server. From this page you can also:

  • Edit the configurable settings of a request handler
  • Add a new request handler
Edit

Click this to edit configurable settings for the server or one of the request handlers.

Module Name

Shows the filename of the request handler.

Module Path

Shows the path where the request handler file is located.

Current Status

Shows the current status of the request handler. The possible statuses are:

Enabled | The handler is enabled
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Disabled | The handler is disabled
Status Log

Shows information about the most recent event that occurred on this handler.

Custom Configuration

This field is not used.

Description

Shows an optional text description of the handler.

Add

Click this to add a new request handler.

  • Edit Handler
  • Add Handler
Parent topic: Enterprise Server Administration Console Help Pages


Edit Handler

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of a request handler

Module Name

Specify the name of the request handler, up to 255 characters.

Note: Note:

You can change the name of a handler only when the server has the status "Stopped". You cannot include angle brackets (<>) or ampersands (&) in the name.

Current Status

Shows the current status of the request handler. The possible statuses are:

Enabled | The handler is enabled
Invalid | An error has occurred such that it has not been possible to set the status to any other value
Disabled | The handler is disabled
New Status

Choose a status from the list. The possible statuses are:

Enabled | The handler is enabled. This is the default
Disabled | The handler is disabled
Note:

You can change the status of a handler only when the server has the status "Stopped".

Module Path

Specify the path where the request handler file is located.

Configuration Information

This field is not used.

Description

Specify a text description of the request handler, for example, its purpose and owner. Optional.

Delete

Click this to delete the handler.

Note:

You cannot delete the MFRHBINP request handler.

Parent topic: Handlers


Add Handler

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add a new request handler to a server.

Module Path

Specify the path where the request handler file is located.

Status

Choose a status from the list. The possible statuses are:

Enabled | The handler is enabled. This is the default.
Disabled | The handler is disabled.
Configuration Information

This field is not used.

Description

Specify a text description of the request handler, for example, its purpose and owner. Optional.

Add

Click this to add the handler to the selected server.

Parent topic: Handlers


Packages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to view a list of the implementation packages registered for the currently selected server. From this page you can also:

  • Edit the configurable settings of an implementation package
  • Add a new implementation package
Show

Specify the number of packages to show at a time. If you change this, you have to click Refresh to see the effect.

Previous

Click this to view the previous page of packages. You can click this only if the number of packages is greater than can be shown on one page.

Next

Click this to view the next page of packages. You can click this only if the number of packages is greater than can be shown on one page.

Edit

Click this to edit configurable settings for the implementation package.

Name

Shows the name of the package.

Current Status

Shows the current status of the package. The possible statuses are:

Available | The package is available. This is the default.
Invalid | An error has occurred such that it has not been possible to set the status to any other value.
Disabled | The package is disabled.
Status Log

Shows information about the most recent event that occurred on this package.

Package Module

Shows the name of the library that contains the package, if any.

IDT

Shows the path of the IDT (interface definition table) for the package.

Package Path

Shows the path where the package file is located.

Custom Configuration

This field is not used.

Description

Shows an optional text description of the package.

Add

Click this to add an implementation package.

  • Add Package
  • Edit Package
  • Delete Package
Parent topic: Enterprise Server Administration Console Help Pages


Add Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add an implementation package to the server.

Name

Specify the name of the new package, up to 255 characters. You cannot include angle brackets (<>) or ampersands (&) in the name.

Status

Choose a status from the list. The possible statuses are:

Available | The package is available. This is the default.
Disabled | The package is disabled.
Package Module

Specify the name of the library that contains the new package. You need to specify this only if the program is in a library that has a different name than the package name. Include the extension; library files have the extension .lbr or .dll on Windows, .lbr or .so on UNIX (.lbr or .sl on HP-UX PA-RISC).

IDT

Specify the pathname of the IDT (interface definition table) for the package.

IDT Remains Resident

Check this if you want the IDT to be loaded into the shared memory area while the service is running. This can help performance if the service is frequently used and there are no constraints on shared memory.

Package Path

Specify the path or paths where the executable program or programs are located. Separate paths with semicolons on Windows, and with colons on UNIX. If you do not specify this, the Directory Server looks for the file first in the path included in the interface definition table, and then in the paths specified by the COBDIR environment variable.

Configuration Information

This field is not used.

Description

Text description of the package. Optional.

Add

Click this to add the new package to the server. You must add a listener before you can click Add.

Parent topic: Packages


Edit Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configurable attributes of an implementation package.

Name

Specify the name of the package, up to 255 characters. You can change the name only if the server has the status "Stopped". You cannot include angle brackets (<>) or ampersands (&) in the name.

Current Status

Shows the current status of the package.

New Status

Choose a status from the list. The possible statuses are:

Available | The package is available.
Disabled | The package is disabled.
Package Module

Specify the name of the library that contains the new package. You need to specify this only if the program is in a library that has a different name than the package name. Include the extension; library files have the extension .lbr or .dll on Windows, .lbr or .so on UNIX (.lbr or .sl on HP-UX PA-RISC).

IDT

Specify the pathname of the IDT (interface definition table) for the package.

IDT Remains Resident

Check this if you want the IDT to be loaded into the repository while the service is running. This can help performance if the service is frequently used and there are no constraints on shared memory.

Package Path

Specify the path where the package file is located. If you do not specify this, the Directory Server looks for the file first in the path included in the interface definition table, and then in the paths specified by the COBDIR environment variable.

Configuration Information

This field is not used.

Description

Specify a text description of the package. Optional.

Delete

Click this to delete the package. You cannot delete a package if it is associated with a service.

Parent topic: Packages


Delete Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to delete the selected package.

CAUTION:

Deleting a registered package may cause application connection errors and loss of data

Name

Shows the name of the package.

Package Module

Shows the name of the library that contains the package.

IDT

Shows the path of the IDT (interface definition table) for the package.

Description

Shows a text description of the package.

Parent topic: Packages


Security Configuration Screen Help

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section contains the context sensitive help available when configuring Enterprise Server security. This help is also available from the user interface. To access the help, select Help > This Page from the left pane.

Note: The context help in this section is the most up-to-date version.
  • MF Directory Server Users, Add or Edit
  • Add Resource Class
  • Add Resource Entity
  • Add Security Manager
  • Add to Default ES Security Manager List
  • Add to ES Security Manager List
  • Add to MF Directory Server Security Manager List
  • Configure General Options
  • Confirm Password
  • Configure Journal Options
  • Configure Monitor Options
  • Configure Repository Options
  • Default ES Security Configuration
  • Directory Server Users
  • Edit Resource Class
  • Edit resource entity
  • Edit Security Manager
  • Left Pane Menu Items
  • MF Directory Server Security
  • Remove Security Manager Reference Confirmation
  • Security Managers Pool
  • SSL Options
  • Shut Down the MF Directory Server
  • Update User
  • User Group Members
  • User Groups
  • User Import: another user registry
  • User Import: previous version
Parent topic: Enterprise Server Administration Console Help Pages
Parent topic: Managing an LDAP from the Enterprise Server UI


MF Directory Server Users, Add or Edit

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add new users, select a user for updating or deleting, and to import user accounts. This screen is divided into tabs. The label of the tab indicates the start character(s) of the account IDs that are listed on the tab.

Account ID
The ID for the user account.
Add
Click this to add a new user.
Advanced Configuration (read only)
Displays user information retrieved from the LDAP.
Allow Logon
Indicates whether this user can logon.
Custom Configuration
An area where you can add custom user configurations, if your LDAP allows it.
Description
A description of the user account.
Edit
Click this to select the highlighted user ID for updating or deleting
Import
Click this to import user data from an installation of a previous version of Micro Focus Directory Server.
Journal
Click this to show the Journal page. This page shows the Directory journal, which is a record of Directory Server activity.
Logon
Click this to show the log on page. This menu option is shown only if the session is not currently logged on and the User Access setting on the Options page is "Restricted".
Member of
A comma separated list of the user groups of which the the user is a member.
Name
The full name of the person assigned to this account.
Sessions
Click this to show the Sessions page. This page shows the list of currently logged on Web browser client sessions, and also any bound program client sessions.
Shut Down
Click this to show the Shut Down confirmation page. This page enables you to shut down the Directory Server. This menu option is available only if you logged on with Schema Administrator permission level This menu option is available only if you logged on with Schema Administrator permission level and Directory Server is not running as a Windows service.
Parent topic: Security Configuration Screen Help


Add Resource Class

Use this page to add the details of a new resource class.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Add

Click here to add the new definition.

Class name

Specify the unique name of the resource class.

Description

Specify a description of the resource class.

Parent topic: Security Configuration Screen Help


Add Resource Entity

Use this page to add the details of a new resource entity to the current resource class.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Entity name

Specify the name of the resource entity. This must be unique within the resource class.

Description

Specify a description of the resource entity.

Add

Click here to add the new definition.

Parent topic: Security Configuration Screen Help


Add Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add a new security manager.

Authorized ID and Password

If the module requires credentials to connect to the external security manager, specify them here.

As with the connection path, the content and format of these fields depend on the module that you are using. For details, please see the documentation supplied with the module.

Cache limit:

If the module has a configurable cache for holding responses from the security manager, enter its maximum size in kilobytes here.

Cache TTL:

If the module has a configurable cache for holding responses from the security manager, enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

Note: Enterprise Server and Directory Server also have their own configurable caches for security information. These are checked before submitting queries to the security manager module.
Configuration information

Specify any additional configuration settings that the module requires.

Connection Path:

If the module requires a connection string that tells it how to connect to the external security manager, specify it here.

The information supplied in the string and its format depend on the module that you are using. For details, please see the documentation supplied with the module.

Description

Specify a description of the security manager.

Enabled

Check this to enable this security manager. If it is disabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Module

Specify the module used to access an external security manager or to implement the security rules. If you specify it with a relative path (which includes no path) it is relative to $COBDIR/etc.

Name

Specify the name used to identify the security manager.

Parent topic: Security Configuration Screen Help


Add to Default ES Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add Security Managers to the Default ES Security Manager List. This is the list of security managers (taken from the available pool) that enterprise servers can use to perform security queries.

The screen shows a table that contains the available pool of Security Managers.

Select

Use this to select a security manager for addition to the Default ES Security Manager List.

Name

This column indicates the name that used to identify a security manager.

Module

This column indicates the module used by a security manager to access an external security manager or to implement the security rules.

Used by

This column shows the security manager lists that include this security manager.

Description

The description column indicates the description for a security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Add

Click this to add the currently selected security manager to the Default ES Security Manager List.

Parent topic: Security Configuration Screen Help


Add to ES Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add Security Manager to a particular enterprise server's Security Manager List. This is the list of security manager (taken from the available pool) that the enterprise server can use to perform security queries.

The screen shows a table that contains the available pool of Security Managers.

Select

Use this to select a security manager for addition to the Security Manager List.

Name

This column indicates the name that used to identify a security manager.

Module

This column indicates the module used by a security manager to access an external security manager or to implement the security rules.

Description

The description column indicates the description for a security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Add

Click this to add the currently selected security manager to the Security Manager List.

Parent topic: Security Configuration Screen Help


Add to MF Directory Server Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to add Security Managers to the MFDS Security Manager List. This is the list of security manager (taken from the available pool) that Directory Server can use to perform security queries.

The screen shows a table that contains the available pool of Security Manager.

Add

Click this to add the currently selected security manager to the MF Directory Server Security Manager List.

Description

The description column indicates the description for a security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Module

This column indicates the module used by a security manager to access an external security manager or to implement the security rules.

Name

This column indicates the name that used to identify a security manager.

Select

Use this to select a security manager for addition to the MFDS Security Manager List.

Used by

This column shows the security manager lists that include this security manager.

Parent topic: Security Configuration Screen Help


Configure General Options

Use this page to change configuration settings for the Directory Server.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Maximum Directory Server object count

Specify the maximum number of objects that the repository can hold.

The minimum is 64 objects. The maximum is 9999 objects. The default value is 128 objects.

Generate UDP search requests

When a CCI client request cannot be satisfied by this Directory Server it can forward the request to any other compatible naming services on the local network by issuing the request using a UDP broadcast. You might want to minimize broadcast traffic or force clients to search for locally registered servers by disabling this feature.

The default is enabled.

Restore server states when Directory Server starts up

Check this if you want servers that were previously started when the Directory Server closed down to be restarted when the Directory Server is started. For example, if your system is configured to run Directory Server automatically at system startup, and this flag is checked, then whenever you reboot your machine, Directory Server will attempt to restart any servers that were running when it closed down.

The default is "Disabled".

Save Legacy Micro Focus Servers

Check this if you want legacy Micro Focus servers to be included when you save the Directory Server repository. Legacy Micro Focus servers are CCI servers.

The default is "Disabled".

Servers marked "Started" only when all listeners started

Check this if you want the server status to remain "Stopped" until all of the auto-start and startable listeners (those not marked as Disabled) have been set to "Started" status.

If this is unchecked, the server status is set to "Started" when the first MFCS instance that starts up modifies the server status. This will be shortly after the Communications Process Control Channel listener becomes active. At this point, any remaining listeners for that Communications Process, and any other Communications Processes for that server, will probably still be starting up.

By default this is unchecked.

Clear dynamically assigned address values when servers stop

Check this box to override the option on the individual stop server confirmation page so that the dynamic address values for the server are cleared when it stops. This will happen regardless of whether it is started remotely, from the command line, or from the Enterprise Server Administration GUI.

By default this is unchecked.

Default Process User ID

UNIX only. Specify a default user ID to be attached to all processes started from the Directory Server, for example, service execution processes. You can override this default process user ID for an individual enterprise server by specifying a value for Process User ID on the Edit Server Advanced page. If you do not specify a user ID in either place, all processes run as user root, which can create problems with security and access to files. You can specify either a numeric user ID or a username.

Defaults

Click this to restore the default settings.

Note:
  • If the current number of objects exceeds the default object count, the default is not restored.
Parent topic: Security Configuration Screen Help


Confirm Password

Use this page to confirm your user ID and password after you have changed the mode of Directory Server from Unrestricted to Restricted.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
User ID

Specify your user ID. User IDs are case sensitive.

Password

Specify your password. Passwords are case sensitive.

Parent topic: Security Configuration Screen Help


Configure Journal Options

Use this page to change configuration settings for the Directory Server journal.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Journal

The journal is a file that records some of the Web browser client and program client activity occurring on the Directory Server. It can track usage and help with support issues.

The level of journaling in force affects performance; the more entries written, the more performance is degraded. The scale of the degradation depends on many factors such as file system performance and client traffic; a system with a large number of highly active program clients suffers the most.

Maximum file size

Specify the maximum file size in kilobytes (KB) of the journal file. Once the journal file grows to this size, the most recent journal entries overwrite the oldest journal entries.

The minimum is 32 KB. The default value is 256 KB.

CAUTION:

Changing the size of the journal erases any previous journal entries.

Entries displayed

Specify the number of journal entries that will be displayed on the page at a single time.

The minimum is 5 entries. The default value is 23 entries.

Journal level - Errors only

Check this if you want journal entries to be written for errors only.

Journal level - Errors and warnings

Check this if you want journal entries to be written for errors and warnings only.

Journal level - All information

Check this if you want journal entries to be written for all events.

CTF trace

Check this if you want journal entries to be written through the Consolidated Trace Facility.

Defaults

Click this to restore the default settings.

Note:
  • Restoring the default maximum file size of the journal has the effect of erasing the journal, unless the maximum size is already set to the default.
Parent topic: Security Configuration Screen Help


Configure Monitor Options

Use this page to change configuration settings for the Server Monitor.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Acceptable response time

Specify the interval (in seconds) that the server monitor is to wait for a response after sending a keep-alive request to a server before assuming it is not responding. If you know that the network is normally quiet or busy, you can adjust this time accordingly.

The default value is 5 seconds.

Defaults

Click this to restore the default settings.

Enabled

Check Enabled to start the server monitor. Uncheck it to stop the server monitor at the next keep-alive interval timeout.

The default is Enabled.

Keep-alive interval

Specify the interval (in seconds) that the server monitor is to wait between each cycle of server interrogations. Since each cycle of interrogations takes a finite amount of time, depending on how many servers are registered and how responsive they and the network are, the actual time taken between checks is longer than this interval.

The default value is 60 seconds.

Server Monitor

The server monitor checks whether all enterprise servers registered with the Directory Server and not marked "Stopped" or "Disabled" are responding to potential client requests. If they are, their status is marked as "Started", otherwise, if they are currently marked as "Started" and they are not responding, they are marked as "Not Responding".

Having the server monitor on ensures that Current Status for a server is up to date, even if the server itself cannot contact the Directory Server for some reason, for example, a network connection or machine failure.

Parent topic: Security Configuration Screen Help


Configure Repository Options

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to change configuration settings for the Directory

Repository Location

Specify the type of storage and the location containing the repository. You can store the repository in the file system or in an LDAP repository.

For file system storage, the location is the directory in which the repository data will be stored.

For LDAP storage, the location is the address of the LDAP server that will be used.

In order to store the repository in an LDAP server, the server must be updated to support the Micro Focus configuration objects.

Warning: If you change the location and the destination already contains a repository, you will be warned and given the opportunity to overwrite it or to cancel the operation.
Note: When you specify ldap:// as the storage mechanism, additional fields are displayed for specifying the container in which the data will be stored, and the LDAP user credentials required to write to the container.
Repository Container Distinguished Name

The distinguished name of the LDAP container in which the repository is to be stored.

User DN
The distinguished name of the LDAP user with which to access the repository. This user must have permission to read and write to the container.
User Password
The password of the user with which to access the repository.
Parent topic: Security Configuration Screen Help


Default ES Security Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to define default security settings that can be used with Directory Server and enterprise servers. You can override these defaults for individual servers

Add

Click this to add a security manager from the pool of available definitions.

Allow unknown resources

Check this if you want the security facility to permit access to any unknown resource; that is, any resource for which all entries on the priority list return Unknown.

You might use this in circumstances where you only want to restrict access to some resources.

Allow unknown users

Check this if you want to allow unknown users to log in.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Cache limit:

Enter the maximum size in kilobytes that the Directory Server or enterprise server's security facility can use for caching the results of security queries.

Cache TTL:

Enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

Create audit events

Check this to enable the enterprise server or Directory Server to generate security audit events. These events can be captured and logged by the Audit Facility.

Configuration information

Specify any additional configuration settings that the security facility requires.

Default ES Security Manager List

This is the list of security managers (taken from the available pool) that can be used to perform security queries.

Note: Security managers are queried in the order that they appear in the list. If the Verify against all Security Managers checkbox is not checked, the first manager in the list that responds with a definite answer will determine the result of a security query. See the text for Verify against all Security Managers for more details.

Use the up and down arrows to reposition the selected entry.

Module

This column shows the module used by a security manager to access an external security manager or to implement the security rules.

Name

This column shows the name that used to identify a security manager.

Priority

Indicates the position of the security manager in the sequence in which the security managers are queried.

Select

Use this to select a security manager for removal or for moving to a different position in the list.

Description

The description column shows the description for a security manager.

Remove

Click this to remove the currently selected definition from this list.

Note: The definition is only removed from this list, not from the available pool of definitions.
Use all groups

Check this if a user requesting authorization is to have the permissions of every group to which he or she belongs.

Uncheck this if the user is to have only the permissions of the group specified in the initial security API call that requested verification (authentication) of the user's credentials. Where no group is specified in the verify call, a default group is used.

Verify against all Security Managers

Set this if you want each security query to be checked by all entries on the Security Manager Priority List.

If this is not set, the entries will be queried in the order that they appear on the Priority List until one gives a response of Allow, Deny, or Fail (equivalent to Deny). This response will then be used to decide what action should be taken.

If this field is set, all entries on the list will be queried, and if any returns a Deny or Fail, the access request will be denied. If there are no Deny or Fail responses and at least one of the entries on the list gives Allow as its response, the request will be allowed.

If a security manager does not have a rule for the resource or user specified in the request, it gives a response of Unknown. Whatever the setting of the Verify against all Security Managers field, if all of the entries on the priority list respond with Unknown, the request will be denied unless you have checked Allow unknown resources or Allow unknown users.

Parent topic: Security Configuration Screen Help


Directory Server Users

Use this page to add new users, select a user for updating or deleting, and to import user accounts. This screen is divided into tabs. The label of the tab indicates the start character(s) of the account IDs that are listed on the tab.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Account ID

The ID for the user account.

Name

The full name of the person assigned to this account.

Member of

A comma separated list of the user groups of which the the user is a member.

Description

A description of the user account.

Allow Logon

Indicates whether this user can logon.

Edit

Click this to select the highlighted user ID for updating or deleting

Add

Click this to add a new user.

Import

Click this to import user data from an installation of a previous version of Micro Focus Directory Server.

Parent topic: Security Configuration Screen Help


Edit Resource Class

Use this page to edit the details of a resource class and to add resource entities to the class.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Description

Specify a description of the resource class in this field.

Apply

Click this to apply any change that you have made to the description text.

Delete

Click this to delete this resource class. Note that you cannot delete a resource class that contains resource entities.

Entity

This column specifies the name of each resource entity that is included in this resource class.

Entity Description

This column specifies the description of each resource entity that is included in this resource class.

ACL String

This column specifies the Access Control List (ACL) string of each resource entity that is included in this resource class. The ACL specifies the access rights for the resource entity. Each entry in an ACL is referred to as an Access Control Entry, or ACE. These entries are separated by semi-colons.

Each ACE specifies an actor, which is a user, a wildcard pattern for users, or a group, and one or more permissions that are granted (allow) or denied (deny) to that actor. The format for the ACE is as follows:

setting:actor:action-1,...,action-n

Where:

  • setting is allow or deny
  • actor is the name of a user, a pattern with one or more wildcards (see Wildcards) string that will be matched against the user's name, or a group name or wildcard pattern followed by a space and the word group (eg "ADMIN group")
  • action-1 through action-n are permission tokens:
    • none
    • execute
    • read
    • update
    • add
    • delete
    • control
    • alter
    • all
Edit

Click this to edit the resource entity in this row.

Add

Click this to add a new resource entity to this resource class.

Parent topic: Security Configuration Screen Help


Edit resource entity

Use this page to edit the details of a resource entity.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Description

Specify a description of the resource entity.

ACL String

Specify the Access Control List(ACL) string for the resource entity. The ACL specifies the access rights for the resource entity. Each entry in an ACL is referred to as an Access Control Entry, or ACE. These entries are separated by semi-colons.

Each ACE specifies an actor, which is a user, a wildcard pattern for users, or a group, and one or more permissions that are granted (allow) or denied (deny) to that actor. The format for the ACE is as follows:

setting:actor:action-1,...,action-n

Where:

  • setting is allow or deny
  • actor is the name of a user, a pattern with one or more wildcards (see Wildcards) string that will be matched against the user's name, or a group name or wildcard pattern followed by a space and the word group (eg "ADMIN group")
  • action-1 through action-n are permission tokens:
    • none
    • execute
    • read
    • update
    • add
    • delete
    • control
    • alter
    • all

For example, the following ACL string:

allow:Test group:Execute,Read,Update,Add,Delete;allow:Operator group:Read

assigns the Test group execute, read, update, add and delete permissions for the resource, and assigns the Operator group read permission.

Parent topic: Security Configuration Screen Help


Edit Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to amend the details of a security manager.

Name

Specify the name used to identify the security manager.

Module

Specify the module used to access an external security manager or to implement the security rules. If you specify it with a relative path (which includes no path) it is relative to $COBDIR/etc.

Connection Path

If the module requires a connection string that tells it how to connect to the external security manager, specify it here.

The information supplied in the string and its format depend on the module that you are using. For details, please see the documentation supplied with the module.

Authorized ID and Password

If the module requires credentials to connect to the external security manager, specify them here.

As with the connection path, the content and format of these fields depend on the module that you are using. For details, please see the documentation supplied with the module.

Enabled

Check this to enable this security manager. If it is disabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Cache limit

If the module has a configurable cache for holding responses from the security manager, enter its maximum size in kilobytes here.

Cache TTL

If the module has a configurable cache for holding responses from the security manager, enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

Note: Enterprise Server and Directory Server also have their own configurable caches for security information. These are checked before submitting queries to the security manager module.
Description

Specify a description of the security manager.

Configuration information

Specify any additional configuration settings that the module requires.

Properties

Click this to access pages for the management of users, groups and resources controlled by this security manager.

Important: You will only be able to manage users, groups and resources where the security manager is on the priority list used by Directory Server. That is:
  • if Directory Server uses the Default ES Security configuration, the security manager must be on the Default ES Security manager list
  • if Directory Server uses its own configuration options, the security manager must be on the Directory Server's own security manager list

In addition, the ESM module and the external security manager to which it connects must also support user, group and resource administration via the Security Facility.

Parent topic: Security Configuration Screen Help


Left Pane Menu Items

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following items appear on the left pane menu:

Home menu option

Click this to return to the Home page.

Actions

The heading for menu options that provide administrative actions. The actual number of options displayed below this heading is variable, depending on the permission level of the user.

Logon

Click this to show the log on page. This menu option is shown only if the session is not currently logged on and the User Access setting on the Options page is "Restricted".

Logoff

Click this to log off from an administrative session that is currently logged on. There is no log off confirmation. This menu option is shown only if the session is currently logged on and the User Access setting on the Options page is "Restricted".

Renew

Click this to refresh the IP address information cached by your Directory Server. Use this option when the IP address of the machine running your Directory Server changes.

Directory Server uses the IP address to locate the servers that it manages. When the cached IP address is out of date, Directory Server may be unable to connect to its servers and may report inaccurate information to clients.

Export

Click this to show the Export page. This page enables you to save a copy of the whole repository to a location of your choice. This menu option is available only if you logged on with Administrator or Schema Administrator permission level.

Import

Click this to show the Import page. This page enables you to update the repository with additional objects from an import directory. Imported objects can include servers (along with all of their child objects), and Security Manager definitions. This menu option is available only if you logged on with Schema Administrator permission level.

Delete All

Click this to show the Delete confirmation page. This page enables you to confirm that you want the repository to be completely erased and all registered objects to be deleted. This menu item is available only if you logged on with Schema Administrator permission level.

Shut Down

Click this to show the Shut Down confirmation page. This page enables you to shut down the Directory Server. This menu option is available only if you logged on with Schema Administrator permission level This menu option is available only if you logged on with Schema Administrator permission level and Directory Server is not running as a Windows service.

Configure

The heading for the menu option that enables you to configure Directory Server. This menu heading and its associated menu option are available only if you logged on with Administrator permission level or higher.

Options

Click this to show the Directory Server Options page. This page enables you to configure the Directory Server.

Security

Click this to show the pages used for configuring security options.

Display

The heading for menu options that enable you to view information about the state of the Directory Server and about the events that have taken place on the server.

Directories

Click this to show the Directories page. This page lists all the instances of Directory Server that are running on the network and using the default Directory Server port (86).

Statistics

Click this to show the Statistics page. This page shows statistics and status information about Directory Server.

Sessions

Click this to show the Sessions page. This page shows the list of currently logged on Web browser client sessions, and also any bound program client sessions.

Journal

Click this to show the Journal page. This page shows the Directory journal, which is a record of Directory Server activity.

Help

The heading for menu options that enable you to view documentation about the Directory Server and Enterprise Server Administration.

This page

Click this to view help for the page you are currently viewing and for all the controls on the page.

Contents

Click this to view the Contents of the Enterprise Server documentation.

Note: Note:

For this link to work, you must be using an enterprise server that has a Web listener with the following entry in the [virtual paths] section:

docs=<ES>/docs/html

This enterprise server must be started.

The default enterprise server, ESDEMO, has a web listener with this configuration information. When you create a new enterprise server, a Web listener with the required configuration information entry is automatically created.

Support

Click this to contact Micro Focus Technical Support via the Supportline website to report problems or ask any questions about using Micro Focus software.

Feedback

Click this to open your email client and send general feedback to Micro Focus.

Parent topic: Security Configuration Screen Help


MF Directory Server Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to define the security settings to be used with Directory Server.

Add

Click this to add a security manager from the pool of available definitions.

Allow unknown resources

Check this if you want the security facility to permit access to any unknown resource; that is, any resource for which all entries on the priority list return Unknown.

You might use this in circumstances where you only want to restrict access to some resources.

Allow unknown users

Check this if you want to allow unknown users to log in.

Authenticated client sessions

There are two main methods that a remote user can use to connect to the Directory Server:

  • Using Enterprise Server Administration, which runs in a Web browser. This method is intended for the administrative functions. These clients are known as Web browser clients.
  • Using the underlying MLDAP API, usually via some higher level application interface or product, to carry out some short-lived operation such as to search for the address of a service or to modify the properties of an object. These clients are known as program clients.

If Directory Server is running in Restricted mode, Web browser clients have to authenticate themselves to the Directory Server, carry out any operations, and then log off. (Program clients always run in Restricted mode.) During the time period between the authentication and removal the client is entered into the authenticated client list maintained internally by the Directory Server process. To s the list from accidentally growing too large (not all users or applications log off correctly after they have been authenticated) and also to maintain security, the Directory Server removes both Web browser and program client sessions after a configurable timeout period.

Cache limit:

Enter the maximum size in kilobytes that enterprise server's security facility can use for caching the results of security queries.

Cache TTL:

Enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

Certificate
Custom server certificate path.
Certificate passphrase

Custom server certificate passphrase (optional).

Change

Click this to add a security manager from the pool of available definitions. This button is only present if you are using the MFDS Internal Security Manager. As MFDS Internal Security cannot be used alongside other security managers, when you add the new manager MFDS Internal Security will be removed.

Client program timeout

Specify the maximum interval in seconds since the last activity of a program client before it is automatically unbound.

The minimum value is 60 seconds (1 minute). A value of -1 indicates an infinite timeout period.

The default value is 6000 seconds (100 minutes).

Configuration information

Specify any additional configuration settings that the enterprise server security facility requires.

Create audit events

Check this to enable the enterprise server to generate security audit events. These events can be captured and logged by the Audit Facility.

Description

The description column indicates the description for a security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Keyfile

Custom keyfile path.

Keyfile passphrase

Custom keyfile passphrase.

Module

This column indicates the module used by a security manager to access an external security manager or to implement the security rules.

Name

This column indicates the name that used to identify a security manager.

Priority

Indicates the position of the security manager in the sequence in which the security managers are queried.

Remove

Click this to remove the currently selected definition from this list.

Note: The definition is only removed from this list, not from the available pool of definitions.
Restrict user access

Check this to cause all administrative access to the Directory Server to be authenticated and authorized by the entries on the Security Manager Priority List.

Secure Port

Unless a specific secure port is specified, the SSL connection will use a dynamically assigned port each time the MF Directory Server process is restarted. A fixed known port may be useful if configuring firewall settings.

Security Manager List

This is the list of security managers (taken from the available pool) that MF Directory Server can use to perform security queries.

Note: Security managers are queried in the order that they appear in the list. If the Verify against all Security Managers checkbox is not checked, the first manager in the list that responds with a definite answer will determine the result of a security query. See the text for Verify against all Security Managers for more details.

Use the up and down arrows to reposition the selected entry.

Select

Use this to select a security manager for removal or for moving to a different position in the list.

Use all groups

Check this if a user requesting authorization is to have the permissions of every group to which he or she belongs.

Uncheck this if the user is to have only the permissions of the group specified in the initial security API call that requested verification (authentication) of the user's credentials. Where no group is specified in the verify call, a default group is used.

Use custom server ID certificate

If this is turned off, the default DemoCA root certificate, server certificate, keyfile and passphrase that are installed with the product will be used. For production purposes it is recommended that the default certificates are not used, and that the customers own certificates are specified. In addition, the MF_ROOT_CERT environment variable will need to be set so that the MF Directory Server process can pick up the value of the root certificate path.

Update when external Security Manager properties change
Check this to update the configuration to reflect changes made to any external Security Manager used.
Use default ES Security Manager List

Check this if you want to use your default ES security manager list for Directory Server, rather than the Security Manager List below. To define the default ES Security settings, click Security on the menu on the left hand side, and then click Security > Default ES Security.

Use encrypted connections

Select this if you want to start Enterprise Server Administration so that it requires authorized browser connections to use SSL. If the state is changed from the current active selection then the MF Directory Server process will need to be re-started to use the new setting. If encrypted connections are selected, administrative access must also be set to restricted.

Verify against all Security Managers

Set this if you want each security query to be checked by all entries on the Security Manager Priority List.

If this is not set, the entries will be queried in the order that they appear on the Priority List until one gives a response of Allow, Deny, or Fail (equivalent to Deny). This response will then be used to decide what action should be taken.

If this field is set, all entries on the list will be queried, and if any returns a Deny or Fail, the access request will be denied. If there are no Deny or Fail responses and at least one of the entries on the list gives Allow as its response, the request will be allowed.

If a security manager does not have a rule for the resource or user specified in the request, it gives a response of Unknown. Whatever the setting of the Verify against all Security Managers field, if all of the entries on the priority list respond with Unknown, the request will be denied unless you have checked Allow unknown resources or Allow unknown users.

Web browser timeout

Specify the maximum interval in seconds since the last activity of a Web browser client, for example, a browser refresh, before it is automatically logged off.

The minimum value is 60 seconds (1 minute). A value of -1 indicates an infinite timeout period. We recommend you use this value sparingly and always reset to a finite period as soon as possible. This is because if the Directory Server is running with an infinite Web client timeout, there is more likelihood that an unauthorised user might gain access to the system using an unattended machine; also the Directory Server will tend to become overloaded with clients who have not logged off.

The default value is 300 seconds (5 minutes).

Parent topic: Security Configuration Screen Help


Remove Security Manager Reference Confirmation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server Administration displays this page in the following situations:

  • when you choose to remove a security manager from the MF Directory Server's security manager list and that security manager is the only one present in the list. When the security manager is removed, it is automatically replaced by the MFDS Internal security manager.
  • The MFDS Internal security manager cannot be used in a list that contains other security managers. Therefore, when you choose to add a different security manager to the MF Directory Server's security manager list, the MFDS Internal security manager, if present in the list, will be automatically removed.

This screen checks that you want to proceed with the removal.

Parent topic: Security Configuration Screen Help


Security Managers Pool

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to manage the pool of security managers available for Directory Server and enterprise servers to use for resolving security queries.

You can have multiple definitions for any given external security manager. Each definition may be used by Directory Server and one or more enterprise servers.

Add

Click this to add a new security manager.

Description

The description column shows the description for a security manager.

Edit

Click this to edit details of the currently selected security manager.

Enabled

This column indicates whether or not the security manager is enabled. If it is not enabled, it will be ignored by Directory Server and those enterprise servers that reference it.

Module

This column shows the module used by a security manager to access an external security manager or to implement the security rules.

Name

This column shows the name that used to identify a security manager.

Select

Use this to select a security manager for editing or removal.

Update All
Click this to update the security managers so that they display the correct current status.
Used by

This column shows the security manager lists that include this security manager.

Parent topic: Security Configuration Screen Help


SSL Options

Use this page to set options for encryption and for authentication of online entities.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Accept all clients

Click this to allow all clients to communicate with the server without being checked for an SSL certificate.

Request client certificate, and verify if present

Click this to request the client for a certificate, and to verify the returned certificate. If the client doesn't return a ceritficate, communication continues between the client and server. If a certificate is returned and it fails to verify, communication stops.

If you check this, you must specify the CA root certificates file below.

Require client certificate and verify

Click this to always require a client certificate and to verify it. This ensures that the client is trusted. If a certificate is not returned or it cannot be verified, communication between the client and server is stopped.

If you check this, you must specify the CA root certificates file below.

CA root certificates file

This field is mandatory if you have chosen to request or require a client certificate.

Specify the path and filename of the file containing certificates of root CAs that you trust. This file must contain the CA root certificate of the CA that signed the client's certificate. For example, in the demoCA environment, this is CARootcert.pem in the private directory of the DemoCA area in the client system.

Parent topic: Security Configuration Screen Help


Shut Down the MF Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to confirm that you want to shut down the MF Directory Server.

Note: This is available only if MFDS is running as a program. Under normal circumstances, MFDS runs as a service, and this screen is unavailable.
CAUTION:

Shutting down the server might cause application connection errors and loss of data if currently running applications rely on reaching data registered in the Directory Server repository.

Stop servers before shutting down

Check this if you want the servers to be stopped before the Directory Server stops.

Yes

Click this to shut down the Directory Server. Enterprise Server Administration will no longer be available after you have shut down the Directory Server.

Parent topic: Security Configuration Screen Help


Update User

Use this page to modify the details of registered users and to delete users.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Account ID

Indicates the ID of the accout being edited.

Name

Specify the full name of the person assigned to this account.

Description

Specify a description of the user.

Default Group

Specify a default user group for this user.

Where a user verification request does not specify a group, this default group is used.

Allow Logon

Check this to permit the user to logon.

Member of:

Lists the user groups of which this user is a member. Click a group to select it for removal from this list.

User groups:

Lists all available user groups. Click a group to select it for adding to the Member of list.

Remove-->

Click this to remove the selected group from Member of.

<--Add

Click this to add the selected group to Member of.

New Password

Specify the new password of the user. Passwords can contain alphabetical and numeric characters only and are case sensitive. If you leave this field blank, the existing password is unchanged.

Confirm Password

Specify the case-sensitive new password of the user. If you enter a value that does not match the value in New Password, an error is generated and the existing password is unchanged.

Delete

Click this to delete this user.

Parent topic: Security Configuration Screen Help


User Group Members

Use this page to edit the details of a user group.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Group Members

Lists the members of this user group. Click a member to select it for removal from this list.

Add

Click this to add the specified user to the group. Note that the user must exist.

Remove

Click this to remove the selected member from the group.

Parent topic: Security Configuration Screen Help


User Groups

Use this page to add new groups, and to select a group for updating or deleting.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Name

The name of the group.

Description

A description of the group.

Members

Shows the number of users in the group.

Edit

Click this to select the adjacent group for updating or deleting

Add

Click this to add a new group.

Parent topic: Security Configuration Screen Help


User Import: another user registry

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to import user data to another user registry.

Note: User data is stored in a user definition file called CCIUSERS.dat, located in $COBDIR/etc.

Also, the fields available on this screen depend on whether you are importing from a file or from an LDAP server.

User registry

Specify the location of the user registry from which you want to import users.

If the registry is in a file, the location is the full name of the file.

If the registry is in an LDAP server, the location is the address of the LDAP server.

Note: When you specify ldap:/// as the type of registry, additional fields are displayed for specifying which users are to be imported, and the user credentials required for reading the data from the LDAP server.
Base DN

Specify the base distinguished name for the container from which the user entries will be obtained.

Filter

Specify any filter condition to restrict the list of users imported.

Credentials

Specify the credentials required to access the LDAP server.

User DN:

The distinguished name of the LDAP user with which to access the repository.

Password:

The password of the user with which to access the repository.

Replace all existing user information

Check this if you want all existing users to be removed and replaced with the users that you are importing. If this is not checked, existing users will not be changed and only those users in the import file that are not already present in your repository will be imported.

Replace existing duplicate user information

Check this to replace any existing user that is a duplicate of one being imported.

Import only users who are members of these groups

Restrict the users imported to those within the groups named in this field.

Add imported users into this group

Specify a group to which all imported users should be assigned.

Parent topic: Security Configuration Screen Help


User Import: previous version

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this page to import user data from a previous version of Micro Focus Directory Server.

Note: Prior to this release, user data was stored in a user definition file called CCIUSERS.dat. This was located in the install-dir\base\bin\ for Net Express or install-dir\bin\ where Enterprise Server was installed standalone.

Note also, the fields available on this screen will depend on whether you are importing from a file or from an LDAP server.

User registry

Specify the location of the user registry from which you want to import users.

If the registry is in a file, the location is the full name of the file.

If the registry is in an LDAP server, the location is the address of the LDAP server.

Note:

When you specify ldap:/// as the type of registry, additional fields are displayed for specifying which users are to be imported, and the user credentials required for reading the data from the LDAP server.

Base DN

Specify the base distinguished name for the container from which the user entries will be obtained.

Filter

Specify any filter condition to restrict the list of users imported.

Credentials

Specify the credentials required to access the LDAP server.

User DN:

The distinguished name of the LDAP user with which to access the repository.

Password:

The password of the user with which to access the repository.

Replace all existing user information

Check this if you want all existing users to be removed and replaced with the users that you are importing. If this is not checked, existing users will not be changed and only those users in the import file that are not already present in your repository will be imported.

Replace existing duplicate user information

Check this to replace any existing user that is a duplicate of one being imported.

Import only users who are members of these groups

Restrict the users imported to those within the groups named in this field.

Add imported users into this group

Specify a group to which all imported users should be assigned.

Parent topic: Security Configuration Screen Help


Deploying and Configuring Modernized Applications

Describes how to configure and administer modernized COBOL applications running in the Enterprise Server environment.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • About Modernized Applications
  • Managing Resources
  • Adding and Deleting Services
  • Configuring and Monitoring Services
  • Configuring Implementation Packages
  • Deploying Interfaces Generated by the Interface Mapping Toolkit
  • Deploying EJBs and Resource Adapters
Parent topic: Enterprise Server


About Modernized Applications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

COBOL applications can be modernized so that they run in the Enterprise Server environment. A modernized COBOL application can be deployed as a service that perform the application's operations.

A service provides access to specific business functionality. A COBOL program implemented as a service reads in a parameter block, processes it and returns a results block.

A service that you create within Enterprise Server can contain one or more operations, depending on the name you give the service and which request handler is associated with it (if any). If you create a service with no request handler associated with it or if the name you use does not contain a valid separator, the service and the operation are one and the same. The Enterprise Server documentation uses the term "simple service" for services of this type. System services such as the Deploy service of the default enterprise server instance, ESDEMO are simple services.

  • Service Names and Operations
  • Types of Services Supported
Parent topic: Deploying and Configuring Modernized Applications


Service Names and Operations

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Service names can be of two forms, depending on whether or not the service contains any operations. The two forms are:

  • Names consisting of one part, for example, Test or my_service. Simple services have this type of name.
  • Names consisting of three parts, for example, http:/tempuri.org/wmapserv#Add. The parts are:
    • The service namespace. This is the part of the name before the first pound (#) character
    • The separator, in this case, the pound (#) character
    • The operation name, in this case Add

    Services with operations have this type of name.

    Service names for Web services use the first pound (#) character as a separator, while names for services that form part of a J2EE application use the last period ( ) character, for example, mybinpservice.operation.

    You can include more than one pound character or period in a service name; Enterprise Server will interpret the first pound character or last period character it finds as the separator.

  • The Services Table
  • Configuring Services
Parent topic: About Modernized Applications


The Services Table

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can see the information held in the repository for services by clicking Details against Services in the table of servers on the Home page. The services table is shown below.

Figure 1. Services Table
Services Table

The information is as follows:

  • Service namespace - a unique label within the enterprise server that identifies the service and if it contains operations, groups the operations together
  • Operation - a list of the individual operations within a service; if the service is a simple service, there is just one item in this list, and it bears the same name as the service itself
  • Service class - for Micro Focus use only; set to MF deployment for all deployment services
  • Search order - the order in which services of the same name are sorted for searching purposes
  • Listeners - a list of the listeners allocated to this service
  • Request handler - the request handler for this service
  • Implementation package - the implementation package that provides the business functionality
  • Status information - you can see the current status and the time of the last status change
  • Status log - this supplies information about the most recent event that occurred on this service
  • Custom configuration data - for more information see the section Configuration Information
  • Description

Service display flters control how much service information you can see. These appear at the top of the services table. There are four service display filters:

  • Service: to use this filter, specify the name of the service you want to view; you need only enter enough characters to identify the service uniquely
  • Class
  • Handler
  • Package

Except for Service, each has three options

  • None: choose this to see no services for this filter
  • Some: choose this to see services that have a value for this filter
  • All: choose this to see all services for this filter

For example, to see service details for services of class 1, choose Some in Service Display Filters Class; to see only services that do not have a request handler associated with them, choose None in Service Display Filters Handler; to see all services choose All in all three filters that have options and leave Service blank. Use all the filters in combination to achieve the maximum control over the level of detail you see.

When you first see the Services table, all the filters that have options are set to All and the Service filter is blank.

Parent topic: Service Names and Operations
Related information
Configuration Information


Configuring Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use the Configuration Information field on the Add Service and Edit Service pages for configuration data specific to services.

The [MF client] settings provide configuration for MFCC when it is creating the deployment request.

The [destination] settings are used by mfdepinst when it creates service and package objects in the Directory Server while installing a deployment package (.car file).

Note: These settings are only used when deployment is done via MFCS, using the IMTK or another deployment client. If you run mfdepinst manually from the command line to install a .car file, it is not invoked for a particular deployment service, so it has no deployment service configuration to consult.
[MF client]
scheme=protocol
URL=virtual-directory-name-1/mfdeploy.exe/virtual-directory-name-2
accept=request-data-type
[destination]
listener=listener-name
server=server-name
Parent topic: Service Names and Operations


Types of Services Supported

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server applications deployed as services can be one of three types:

  • Web services

    These are components using standards and mechanisms that enable software components to be invoked across the Web. A client application using a Web service can invoke the service, and pass data to and from it in the form of XML files sent using a standard protocol such as HTTP.

  • J2EE services
Parent topic: About Modernized Applications


Managing Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A COBOL application providing a service that uses external resources, such as databases and files, can manage its own resources or let the application container manage them. A service that manages its own resources is known as application-managed, while a service that does not manage its own resources is known as container-managed.

If a service updates files through Fileshare, you must specify the name and location of an fhredir.cfg file for the enterprise server in which the service runs.

  • Application-managed Services
  • Container-managed Services
  • Mixing Container-managed and Application-managed Services
Parent topic: Deploying and Configuring Modernized Applications


Application-managed Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A service must manage its own resources if:

  • The application accesses files or databases (or both) in a transactional way, and contains transactional logic: that is, it includes COMMITs and ROLLBACKs
  • The application uses a resource manager that we do not support in the Enterprise Server environment; see the list in Supplementary Information.

A service in which the application accesses files in a non-transactional way (that is, it does not includes COMMITs and ROLLBACKs), should be application managed.

A transactional application-managed service must contain all the transactional logic it needs, that is, it must complete with all resources either committed or rolled back.

CAUTION:
Application-managed services are executed in a similar way to applications in a conventional execution environment such as Enterprise Server or Enterprise Server. One of the main differences is that the process is not terminated at the end of execution of the service.
Parent topic: Managing Resources


Container-managed Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If an application running as a service uses databases and files but does not contain any transactional logic, it can let the application container manage its resources.

The application container must know in advance what resource managers will be required. You define resources not by service, but by enterprise server instance. You can only define resource managers that are XA-compliant.

When an enterprise server instance and its service execution processes start up, the enterprise server manager opens connections to all the resources that might be needed by the services that run in that enterprise server instance. When a container-managed service is invoked, the enterprise server manager performs all file and database actions that it requires.

The application container manages databases by issuing XA commands.

The application container decides whether to commit or roll back resources using information supplied when the enterprise server instance was created and deployed in your COBOL development system. However, if there is an error in the application container itself, resources are always rolled back.

Parent topic: Managing Resources


Mixing Container-managed and Application-managed Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can mix container-managed and application-managed services in the same enterprise server, but in these circumstances it is even more important that the application-managed services complete with all resources either committed or rolled back. This is because when the application container commits or rolls back resources on behalf of a container-managed application, it commits or rolls back all outstanding updates, including any outstanding from application-managed services that ran previously.

Parent topic: Managing Resources


Adding and Deleting Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can add services and implementation packages to an enterprise server instance, and update and delete them whether or not the enterprise server instance is running.

If the enterprise server instance is running (that is, if it has the status "Started") when you are adding services and packages, the changes are immediately reflected in the enterprise server. As long as the service is not currently responding to a client request, any updates are also accepted and take immediate effect.

You cannot delete a service, package or request handler if the resources are in use by a client request. You cannot delete a package if it is associated with a service, whether or not the service is running. If a service has operations, you can delete a service and all its operations and packages in one step, or you can delete individual operations and packages.

When you delete services, packages and request handlers, you are deleting objects in the Directory Server repository, not physical files. Every time a developer deploys a service using the Deploy tool or the imtkmake command, a new directory is created in the enterprise server's deploy directory to hold all the deployed files. If a developer redeploys a service that has already been deployed, the old deployment directory is no longer referenced, since the old service and package objects will have been deleted. You might want to delete old deployment directories from time to time.

If an enterprise server instance is running and you add, edit or delete resources, administration messages are sent to the enterprise server console indicating the success or otherwise of your changes.

It is possible for the Directory Server repository to become out-of-step with an enterprise server instance if the Directory Server accepts updates that the enterprise server instance rejects. If this happens you should stop the server and restart it to enable it to pick up the updates.

  • Creating Services Manually
  • To Add a Service to an Enterprise Server Instance
  • To Associate a Package with a Service
Parent topic: Deploying and Configuring Modernized Applications


Creating Services Manually

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you add services manually to an enterprise server instance, you need to create the objects for them and their relationships in a certain order, as follows:

  1. Add the implementation package to the enterprise server instance
  2. Add one or more service listeners
  3. Add the service, and associate the listener or listeners, implementation package and request handler with it
Parent topic: Adding and Deleting Services


To Add a Service to an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details against Services in the Objects column for the server you want to add the service to.
  2. Click Add.
  3. Specify a name for the service in Name.
  4. If you have more than one service of the same name in the repository, specify a search order for the service in Search Order. The lower the search order, the higher the search priority .
  5. If you want to enable clients to search for services by class, specify the class in Service Class.
  6. Change the default value in Version, if required.
  7. Choose the type of transaction management appropriate to this service: check either Application or Container.
  8. Click a listener you want to use on this service in Available Listeners and then click Add. You can repeat this step to add extra listeners. The listener is added immediately.
  9. Click the request handler you want to use on this service in Available Request Handlers and then click Select Handler. The selection is active immediately.
  10. Click the implementation package that is to provide the service functionality in Available Packages and then click Select Package. The selection is active immediately.
  11. Choose a status for the service from the list in Initial status.
  12. Specify any configuration information the service requires in Configuration Information.
  13. Specify a text description of the service in Description (optional).
  14. Click Add.
Note:
  • You can also reach the Add Service page by clicking Edit to the left of the server to which you want to add the service, clicking the Services tab and clicking Add.
  • You do not have to select a request handler and package for the service when you first add it to the server. You can do this at a later time by going to the Edit Service page.
Parent topic: Adding and Deleting Services
Parent topic: Work with Services
Related information
To Add a Package to an Enterprise Server Instance


To Associate a Package with a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab and then click Add.
  3. Click Edit to the left of the row containing the service with which you want to associate the package.
  4. In Available Packages click the package that you want to associate with the service.
  5. Click Select Package.
Note:

A service can have just one package associated with it.

Parent topic: Adding and Deleting Services
Parent topic: Work with Packages


Configuring and Monitoring Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you are running services on an enterprise server instance, you need to ensure that services are starting and stopping as expected, and that no service is using more resources than expected.

The Monitor page enables you to view the performance of services, providing information about:

  • The average latency, in hundredths of a second.
  • The average time taken to complete a task, in hundredths of a second.
  • The number of tasks completed per second.

For example, if the average time taken to complete a task is large, this would indicate that a service is a long running or stateful service. If the number of tasks completed per second suddenly rises beyond what you expect, this might indicate that a task is repeatedly calling another task in error.

  • Services and Permissions
  • To Monitor Services
  • To Record Service Input and Output
  • To Add a Service for Integration with the Micro Focus Development Tools
  • To Change the Status of a Service
  • To Delete a Simple Service or an Operation
  • To Delete a Service with Operations
  • To Edit a Service
  • To Switch Logging On for a Service
  • To View Services for an Enterprise Server Instance
Parent topic: Deploying and Configuring Modernized Applications


Services and Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have Modify permission level or higher you can:

  • Edit the attributes of a service
  • Switch logging on or off for a service. When logging is on, the service's request and result blocks are written to the enterprise server's dump data set
  • Change the status of a service between available and disabled

If you have Add/Delete permission level or higher you can also:

  • Add a service
  • Delete a simple service or operation
  • Delete a service with operations. When you delete a service with operations you delete all the operations associated with it. You can also delete the packages associated with it
Parent topic: Configuring and Monitoring Services


To Monitor Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To monitor services

  • Click either:

    • Monitor, 1 - This displays the Monitor (1 Minute Intervals) page. Use this to monitor the current situation. This page displays information on the last 32 minutes of activity.
    • Monitor, 15 - This displays the Monitor (15 Minute Intervals) page. Use this to gain information on how the system is performing overall. This page displays information on the last eight hours of operation.
Parent topic: Configuring and Monitoring Services
Parent topic: Administer a Server Using ESMAC


To Record Service Input and Output

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To record service input and output

  1. Click Services.

    The Services page is displayed.

  2. Click Details for the service for which you want the input and output to be recorded.

    The Services page is displayed.

  3. Click the Log I/O dropdown.

    Select Dump.

  4. Click Change.
Note:

If you set input and output to be recorded, they are only recorded during this enterprise server session. If you stop and restart the enterprise server, input and output will no longer be recorded.

If you want input and output to always be recorded, you can specify this using Enterprise Server Administration.

Parent topic: Configuring and Monitoring Services
Parent topic: Administer a Server Using ESMAC


To Add a Service for Integration with the Micro Focus Development Tools

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details in the Object column for the server you want to add the service to.
  2. Click Add.
  3. In both Name and Service Class type: MF ES
  4. Leave the type of transaction management as Application.
  5. In Available Listeners, select the line containing Web Services and J2EE. Then click <-Add below this field.
  6. In Description type a suitable description, such as ES utility service.
  7. Click Add.
Note:
  • You can also reach the Add Service page by clicking Edit to the left of the server to which you want to add the service, clicking the Services tab and clicking Add.
  • Do not associate this service with a handler.
Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Change the Status of a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details against Services in the Objects column for the server you want to change.
  2. Click Edit in the Operation column for the service whose status you want to change.
  3. Choose the new status from the list in New Status.
  4. Click Apply.
Note:

Depending on the status of the change request, one of three messages is displayed in the Enterprise Server Administration GUI status bar:

  • MDS0112I Update success
  • MDS0111W Update request failure

In the case of a failure the state of the service, as reported by the ES Administration GUI, changes from "Available" or "Disabled" to a pending state. The next time the ES instance starts it will use the new configuration.

  • MDS0110W The specified configuration change may not take effect until the server is restarted

The state of the service, as reported by the Enterprise Server Administration GUI, changes from "Available" or "Disabled" to "Changes made to service: a server restart may be required for the new configuration to take effect". To check whether the service update was effective, use the ES Monitor and Control HTML GUI and select the "Services" resource list page.

Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Delete a Simple Service or an Operation

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

Deleting a registered service might cause application connection errors and loss of data.

  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Services in the Objects column for the server that owns the service you want to delete.
  3. Click Edit in the Operation column for the simple service or operation that you want to delete.
  4. Click Delete.
  5. Click OK on the confirmation page.
Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Delete a Service with Operations

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

Deleting a registered service might cause application connection errors and loss of data.

  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking
    expand button
  2. Click Details against Services in the Objects column for the server that owns the service you want to delete.
  3. Click Delete to the left of the row containing the service with operations that you want to delete. You see a page summarizing what you have requested.
  4. If you want to delete the packages associated with the operations, check Delete associated packages.
  5. Click OK.
Note:

When you delete a service, you are removing the service object from the Directory Server repository; the actual deployed files that make up the service are not deleted. For information on deleting old deployed files, see the link in Related Topics.

Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Edit a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

Changing the properties of a registered service might cause application connection errors and loss of data.

  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Services in the Objects column for the server you want to edit.
  3. Click Edit in the Operation column for the service that you want to edit.
  4. Update the attributes of the service as required.
  5. Click OK.
Note:

If you make any changes to the listener or listeners, request handler or package associated with the service, the changes take effect immediately, not when you click OK.

Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To Switch Logging On for a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Details in the Objects column for the server that owns the service for which you want to switch logging on.
  2. Click Edit in the Operation column for the service for which you want to switch logging on.
  3. Check Logging.
  4. Click OK.
Note:

The effect of switching logging on is that the service's request and response blocks are written to a diagnostics file each time the service is invoked. This file is stored in the server's system directory, which defaults to /var/mfcobol/es/es-name where es-name is the name of the enterprise server. The file is named casdumpa.rec (or it might be named casdumpb.rec if you specified a maximum diagnostics file size on the Edit Server page).

You can format and view the information from the Edit Server > Diagnostics > ES Console page. The client request is shown in a block named user-storage-type under the part of the dump entitled CAS-REQ. The server response is shown in a similar block under the title CAS-RESP.

Only switch logging on if you need diagnostics as it degrades performance.

Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


To View Services for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Services in the Objects column for the server for which you want to view services.
Parent topic: Configuring and Monitoring Services
Parent topic: Work with Services


Configuring Implementation Packages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An implementation package defines the application that provides the business functionality.

  • The Packages Table
  • Configuring Packages
  • Configuring Request Handlers
Parent topic: Deploying and Configuring Modernized Applications


The Packages Table

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can see the information held in the repository for packages by clicking Details next to Packages in the table of servers on the Home page. The packages table is shown below.

Figure 1. Packages Table
Packages Table

The information is as follows:

  • Name – this is unique in an enterprise server
  • Current status
  • Status log – this supplies information about the most recent event that occurred on this package
  • Package module – the name of the library containing the package, if it is part of a library
  • IDT – the name of the interface definition table (IDT) for this package
  • Package path – the location of the package module
  • Custom configuration data - this field is not used
  • Description
Parent topic: Configuring Implementation Packages


Configuring Packages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have Modify permission level or higher you can:

  • Edit the attributes of a package
  • Change the status of a package between available and unavailable
  • Associate a package with a service
  • Disassociate a package from a service

If you have Add/Delete permission level or higher you can also:

  • Add a package to an enterprise server
  • Delete a package, as long as it is not associated with any service

Outside Enterprise Server Administration, you can delete old deployment directories.

  • To Add a Package to an Enterprise Server Instance
  • To Delete a Package
  • To Edit a Package
  • To Disassociate a Package from a Service
  • To View Packages for an Enterprise Server Instance
  • To Delete Old Deployed Package Files
Parent topic: Configuring Implementation Packages


To Add a Package to an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab and then click Add.
  3. Specify a name for the package in Name.
  4. Choose a status from the list in Status.
  5. If the entry point that exposes this service is in a library that has a different name than the package itself, specify the name of the library in Module Package. Include the extension; library files have the extension .lbr or .so (.lbr or .sl on HP-UX PA-RISC).
  6. Specify a full pathname for the interface definition table (IDT) in IDT.
  7. Check IDT Remains Resident if you want the IDT to be loaded into the repository while the service is running. This can help performance if the service is frequently used and there are no constraints on shared memory.
  8. Specify a full pathname for the executable file in Package Path. If you have set the COBPATH environment variable at enterprise server level in Configuration Information in the Add Server or Edit Server page, you must specify $COBPATH here, to add the value set at enterprise level to the search path for this package.
  9. Ignore Configuration Information; this field is not used.
  10. Specify a text description of the package in Description (optional).
  11. Click Add.
Parent topic: Configuring Packages
Parent topic: Work with Packages
Related information
To Add a Service to an Enterprise Server Instance


To Delete a Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab to display the packages for the enterprise server instance.
  3. Click Edit to the left of the row containing the package that you want to delete.
  4. Click Delete for the package.
  5. Click Delete on the confirmation page.
Note:
  • You can also delete a package by using the mfpackage command.
  • You cannot delete a package if it is associated with any service.
  • When you delete a package, you are removing the package object from the Directory Server repository; the actual deployed files that make up the package are not deleted.
Parent topic: Configuring Packages
Parent topic: Work with Packages


To Edit a Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click Edit to the left of the row containing the package that you want to edit.
  3. Update the attributes of the package as required.
  4. Click Apply.
Parent topic: Configuring Packages
Parent topic: Work with Packages


To Disassociate a Package from a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab and then click Add.
  3. Click Edit to the left of the row containing the service from which you want to disassociate the package.
  4. In Available Packages click the package that you want to replace the currently associated package.
  5. Click Select Package.
Note:

A service can have just one package associated with it.

Parent topic: Configuring Packages
Parent topic: Work with Packages


To View Packages for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration screen, click Edit to the left of the server to which you want to add the package.
  2. Click the Packages tab to display the packages for the enterprise server instance.
Parent topic: Configuring Packages
Parent topic: Work with Packages


To Delete Old Deployed Package Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:
Use this procedure with great care. Be sure that you are deleting the correct directory, and delete the service containing the packages from the Directory Server repository before you delete the old package files.
  1. Go to the Deploy folder of the enterprise server to which the service was deployed. By default this is $COBDIR/deploy. Here you will find several directories with names of the form: service-name.random-string where service-name is the name of the service supplied during the creation of the service interface, and random-string is a string of random characters generated by the deploy process.
  2. Identify the directory that you want to delete; the date and time of creation of the directory are probably the best guide.
  3. Right-click the directory and click Delete on the popup menu.
Parent topic: Configuring Packages
Parent topic: Work with Packages


Configuring Request Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A request handler is software that receives a client request for access to the service, and translates the request into a form that the application providing the business functionality can understand. The following request handlers are provided with Enterprise Server :

  • MFRHSOAP – handles requests that use SOAP (Simple Object Access Protocol). These are requests for Web services. They are coded in XML.
  • MFRHBINP – handles binary requests made by the Micro Focus J2EE connector.
  • The Request Handlers Table
  • Configuring Handlers
Parent topic: Configuring Implementation Packages


The Request Handlers Table

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can see the information held in the repository for request handlers by clicking Details against Request Handlers in the table of servers on the Home page. The request handlers table is shown below.

Figure 1. Request Handlers Table
Request Handlers Table

The information is as follows:

  • Module name
  • Module path
  • Current status
  • Status log – this supplies information about the most recent event that occurred on this request handler
  • Custom configuration data - this field is not used
  • Description
Parent topic: Configuring Request Handlers


Configuring Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have Modify permission level or higher you can:

  • Edit the attributes of a request handler
  • Change the status of a request handler between available and unavailable
  • Associate a request handler with a service
  • Disassociate a request handler from a service

If you have Add/Delete permission level or higher you can also:

  • Add a request handler to an enterprise server instance
  • Delete a request handler. You cannot delete MFRHBINP
  • To Add a Request Handler to an Enterprise Server Instance
  • To Edit a Request Handler
  • To Associate a Request Handler with a Service
  • To Disassociate a Request Handler from a Service
  • To Delete a Request Handler
  • To View Request Handlers for an Enterprise Server Instance
Parent topic: Configuring Request Handlers


To Add a Request Handler to an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server you want to add the request handler to.
  3. Click Add.
  4. Specify a name for the request handler in Module Name.
  5. Specify a full pathname for the request handler in Module Path.
  6. Choose a status from the list in Status.
  7. Ignore Configuration Information; this field is not used.
  8. Specify a text description of the request handler in Description (optional).
  9. Click Add.
Note:

You can also reach the Add Handler page by clicking Edit to the left of the server to which you want to add the handler, clicking the Handlers tab and clicking Add.

Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To Edit a Request Handler

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server that owns the request handler you want to edit.
  3. Click Edit to the left of the row containing the request handler that you want to edit.
  4. Update the attributes of the request handler as required.
  5. Click OK.
Note:

Any changes that you make only affect the request handler object that the current server owns. Request handler objects of the same name in other enterprise servers are unaffected.

Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To Associate a Request Handler with a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button.
  2. Click Details against Handlers in the Objects column for the server that owns the service with which you want to associate the request handler.
  3. Click Edit to the left of the row containing the service that you want to associate the request handler with.
  4. In Available Request Handlers click the request handler that you want to associate with the service.
  5. Click Select Handler.
Note:

A service can have just one request handler associated with it.

Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To Disassociate a Request Handler from a Service

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server that owns the service from which you want to disassociate the request handler.
  3. Click Edit to the left of the row containing the service from which you want to disassociate the request handler.
  4. In Available Request Handlers click the request handler that you want to replace the currently associated request handler.
  5. Click Select Handler.
Note:

A service can have just one request handler associated with it.

Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To Delete a Request Handler

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server that owns the handler you want to delete.
  3. Click Edit to the left of the row containing the request handler that you want to delete.
  4. Click Delete.
  5. Click OK on the confirmation page.
Note: You cannot delete a request handler if it is associated with any service. You cannot delete the MFRHBINP request handler.
Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


To View Request Handlers for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If the table of servers on the Home page is being displayed in summary form, expand it by clicking expand button
  2. Click Details against Handlers in the Objects column for the server for which you want to view request handlers.
Parent topic: Configuring Handlers
Parent topic: Work with Request Handlers


Deploying Interfaces Generated by the Interface Mapping Toolkit

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Explains the process of deploying a service interface created with the IMTK such that it can run as a service on an enterprise server instance. For complete information on creating service interfaces, see Interface Mapping using the IMTK .

  • Service Interface Deployment Package
  • Service Interface Deployment Process
  • Deploying Java Service Interfaces
  • To add or remove application files to deploy
  • To associate an enterprise server with a project
  • To generate and deploy a service interface from the IDE
  • To generate and deploy a service interface using imtkmake
  • To deploy to a remote enterprise server
  • To redeploy a service interface
  • To install a deployment package using the mfdepinst command
  • To generate clients
Parent topic: Deploying and Configuring Modernized Applications


Service Interface Deployment Package

Restriction: This topic applies only when the Enterprise Server feature is enabled.
A service interface deployment package is contained in a COBOL Archive (.car) file, which is a standard zip archive that includes the following:
manifest file
An XML document that contains deployment information such as the name of the service and a description of the .car file.
interface definition table
A file that describes the service interface. The file extension is .idt.
specified package files
Other files optionally added to the package.

The name of a deployment package file is myservice.car where myservice is the name of your service interface. By default, Visual COBOL generates the .car file in your project's \myservice\myservice.deploy directory.

Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit


Service Interface Deployment Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic describes the process of deploying a service interface and presents three possible deployment scenarios.

The process of deploying a service interface to Enterprise Server involves several steps. While all steps must be completed, you have several options as to how to complete each one.

Important: Before deploying a service interface, you must create an enterprise server instance on Enterprise Server and configure it to run your COBOL application.
The basic deployment process for all types of service interfaces created using the IMTK includes:
  1. Start your enterprise server instance.
  2. Using either the IMTK Deploy tool or the imtkmake command with the -generate option, create a deployment package (.car file).
  3. Copy the deployment package to the system where your enterprise service instance is running. This is done automatically when you create the deployment package from the IMTK Deploy tool or as you install the deployment package using the imtkmake command.
  4. Install the deployment package. This is done automatically when you create the deployment package from the IMTK Deploy tool. If you have generated the deployment package using imtkmake, do this using the imtkmake command with the -deploy option, or the mfdepinst command. You can also install the deployment package manually.
  5. From the Enterprise Server Administration console, add the service interface to the Micro Focus Directory Server. This is done automatically when using the Deploy tool, the imtkmake command, or the mfdepinst command.
  6. Add the service to the enterprise server instance. This is done automatically when using the Deploy tool, the imtkmake command, or the mfdepinst command.

The following scenarios cover three possible deployment methods. You can use one of these, or design one of your own that includes all of the required steps:

Scenario 1: Deploy using IDE tools

  1. From Server Explorer, associate your enterprise server instance with the project containing your service interface.
  2. From Server Explorer, start the enterprise server instance if not already started.
  3. Set deployment properties for your service interface. Depending on the type of service interface, these properties vary. See Properties - Service Interface for more information.
  4. Deploy the service interface by right-clicking the service interface on the , and selecting Deploy from the context menu.

Scenario 2: Deploy using imtkmake

  1. From a Visual COBOL command prompt in the directory that contains your COBOL program file, execute the imtkmake command using the -generate option and appropriate parameters.
  2. Execute the imtkmake command using the -deploy option and appropriate parameters.
Note: You can also use the -generate and -deploy options together. See the imtkmake command reference topic for complete details on using the imtkmake command.

Scenario 3: Deploy manually

While we recommend that you use one of the first two deployment scenarios, it is possible to perform all the deployment steps manually without a deployment package. You can create all the necessary pieces, copy them manually to the Enterprise Server system, and add package and service objects to the configuration from the Micro Focus Directory Server interface. For more information, see Work with Packages and Work with Services.

Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit


Deploying Java Service Interfaces

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you deploy a Java service interface, this produces an EJB or Java Bean and several accompanying files that are copied to the appropriate enterprise server.

Once a Java service is ready for use in a production environment, you should deploy it to an enterprise server using the .car file generated during the last deployment. You can either use the mfdepinst command to deploy the .car file, or you can deploy it manually.

Note:
  • If the service has been mapped as an EJB interface, you might need to perform one or both of the following tasks in addition to deploying the .car file:
    • Deploy the EJB to a J2EE application server
    • Deploy a resource adapter
  • If you generate a client for your Java service, the .car file is deleted from the deployment folder. When setting up your service in a production environment, be sure to deploy this file before generating a client.
Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit


To add or remove application files to deploy

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In , right-click a COBOL program-based service interface, and select Properties.
  2. Add or remove application files as required.
Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit
Parent topic: Deploy Service Interfaces to Enterprise Server


To associate an enterprise server with a project

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In Server Explorer, expand Micro Focus Servers to see a list of available enterprise server instances.
  2. Right-click the enterprise server instance with which to associate the project; then click Associate with project > projectName.
Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit
Parent topic: Deploy Service Interfaces to Enterprise Server
Related information
To generate and deploy a service interface from the IDE


To generate and deploy a service interface from the IDE

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. From the IDE, associate an enterprise server with the project containing the service interface you want to deploy.
  2. Make sure that the enterprise server that runs your application is started.
  3. Ensure that you have set all appropriate properties for your service interface.
  4. In , right-click your service interface; then select Deploy on the context menu.
Note:
  • Enterprise Server Administration lists your deployed service as a service of the enterprise server running your application. You must delete the service from your enterprise server before you can redeploy it.
  • You can also deploy your service interface to an enterprise server running under UNIX.
Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit
Parent topic: Deploy Service Interfaces to Enterprise Server
Related information
To associate an enterprise server with a project


To generate and deploy a service interface using imtkmake

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Start a Visual COBOL command prompt.
  2. Change to the directory that contains your COBOL program file.
  3. Enter the following:
    imtkmake -generate -deploy service=service-name type=service-type server=server-name,deployer-name [optional-parameters]
    where:
    service-name | The name of your service interface.
    service-type One of:
    • EJB
    • J2SEbean
    • WebService
    server-name | The enterprise server to which you want to deploy the service .
    deployer-name | The name of a deployment service on that enterprise server.
    optional-parameters | Optional parameters available with the imtkmake command. See the imtkmake command reference topic for complete information.
Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit
Parent topic: Deploy Service Interfaces to Enterprise Server


To deploy to a remote enterprise server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In the Server Explorer, right-click Micro Focus Servers, and select MFDS Administration from the context menu.
  2. Specify either the Host name or the IP address of the remote server.
  3. In the Port field, type the number of the port you want to use (default is 86); then click OK.
Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit
Parent topic: Deploy Service Interfaces to Enterprise Server


To redeploy a service interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Start Enterprise Server Administration.
  2. Delete the service from the enterprise server instance.
  3. Deploy the service using the deployment method of your choice.
  4. Confirm that the service has been successfully deployed by refreshing Enterprise Server Administration.
Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit
Parent topic: Deploy Service Interfaces to Enterprise Server


To install a deployment package using the mfdepinst command

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If you don't already have one, generate a COBOL archive (.car) file using the Deploy tool or the imtkmake command.
  2. Copy the .mfdeploy file, located by default in $COBDIR/deploy, to the parent directory of the .car file that you want to deploy. For example, if the .car file is in $COBDIR/deploy/test , the .mfdeploy file must be copied to $COBDIR/deploy.
  3. Open the .mfdeploy file in a text editor, and edit the MFES_SERVER line. By default this is set to ESDEMO. Change it to specify the name of the enterprise server you want to use, as follows:

    MFES_SERVER=myserver

  4. Deploy the .car file using the mfdepinst command. For example, to deploy the services in myservice.car, enter the following at a command prompt:
    mfdepinst myservice.car
Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit
Parent topic: Deploy Service Interfaces to Enterprise Server


To generate clients

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • In , right-click a service interface; then click Generate Client from the context menu.
Parent topic: Deploying Interfaces Generated by the Interface Mapping Toolkit
Parent topic: Deploy Service Interfaces to Enterprise Server


Deploying EJBs and Resource Adapters

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An EJB running a COBOL service runs in two places: the COBOL service runs under an enterprise server, and the EJB and client run under a third party J2EE application server, such as WebSphere or WebLogic.

Resource adapters enable EJBs deployed on J2EE to communicate with COBOL on an enterprise server. Resource adapters are also known loosely as J2EE connectors

  • Enterprise Server Acting as a Resource Manager
  • Deploying EJBs Overview
  • Resource Adapters Supplied by Micro Focus
  • Deployment Descriptors that Are Required
  • CustomRecord and the RuntimeProperties Support
  • Third Party Application Server Deployment
  • Troubleshooting
Parent topic: Deploying and Configuring Modernized Applications


Enterprise Server Acting as a Resource Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

J2EE clients run in a J2EE application server such as IBM WebSphere or Oracle WebLogic. When a service is processing requests from a J2EE client, the J2EE application server can be a transaction manager coordinating updates to all the resources involved in a transaction. In this situation, the enterprise server instance behaves like a resource manager and responds to commit and rollback requests from the J2EE application server, whether the COBOL service is container-managed or application-managed.

Parent topic: Deploying EJBs and Resource Adapters


Deploying EJBs Overview

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An EJB running a COBOL service runs in two places: the COBOL service runs under an enterprise server, and the EJB and client run under a third party J2EE application server, such as WebSphere or WebLogic.

You deploy the COBOL service from the .car file.

You deploy the EJB and client by deploying the following to a J2EE application server:

  • The enterprise archive file myservice.ear. This file is created automatically when you generate a Java client. The file contains the:
    • EJB archive file myservice.jar. This file is created when you generate a client and also when you use the Deploy tool to deploy the service interface.
    • Client archive file myservice.war. This file is created when you generate a client.

    If you haven't generated an .ear file, but have only the .jar file, you might be able to deploy the .jar file instead. Your J2EE application might require you to package the .jar file into an .ear before deploying it, or you might find it simpler to do that.

  • One of the supplied resource adapters, mfcobol*.rar. A resource adapter enables the EJB to communicate through its J2EE application server with an enterprise server. Resource adapters are also known as J2EE connectors and they are packaged in resource archive (.rar) files.

Many J2EE application servers are supported, such as WebLogic and WebSphere. Each application server has different deployment requirements and different utilities to help.

  • Deploying EJBs
  • To Add Micro Focus Support for EJBs
  • To Create an .ear File for your EJB
  • To Deploy to WebLogic
  • To Deploy to WebSphere
  • To Deploy to JBoss
Parent topic: Deploying EJBs and Resource Adapters


Deploying EJBs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Deploying EJBs involves configuring them in the third party application server on the J2EE machine, so that the EJBs, resource adapter and Enterprise Server can locate each other.

When you deploy an EJB you use the interface for your third-party application server. Many application servers provide a Web-based interface, such as the WebLogic Server Console, which takes you step by step through the deployment process. Most third-party application servers require the EJB to be packaged in an application .ear file, together with the client and all the necesssary deployment descriptors and other files.

If you don't have an application .ear file, you can often use your application server's administration interface to create one, or you can use the jar command.

Parent topic: Deploying EJBs Overview


To Add Micro Focus Support for EJBs

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Locate the file mfejblib.jar, which contains the Micro Focus support for EJBs.

    Specific versions of this file are supplied for each supported application server and J2EE version. They are available in subdirectories under $COBDIR/javaee in your COBOL system installation or the CD or DVD. They are in the following the application server subdirectories:

    • javaee5/ibmwebsphere7
    • javaee5/jboss5
    • javaee5/oracleweblogic10
    • javaee6/ibmwebsphere8
    • javaee6/ibmwebsphere85
    • javaee6/jboss6
    • javaee6/oracleweblogic1211
  2. Copy mfejblib.jar to the root directory of your enterprise archive file (.ear). By default, the mfejblib.jar belongs in the root because the classpath is set to this in the EJB's manifest.mf file.

    If you copy mfejblib.jar to a different directory, you need to change the classpath in the manifest.mf file in the EJB's .jar file, which is in myservice/Repos/myservice.deploy .

  3. Add the mfejblib.jar file to the archive file that you want to deploy.

    For most application servers, you can do this using their administrative tools. Alternatively, you can use a jar command similar to the following:

    jar -uvf myApplication .ear mfejblib.jar

Parent topic: Deploying EJBs Overview
Parent topic: Deploy to J2EE Application Servers


To Create an .ear File for your EJB

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have generated a client and EJB together, they are automatically packaged into an enterprise archive file (.ear) and you do not need to do this. Otherwise:

  1. Package the EJB's .jar file into an .ear for your application. To do this use a jar command similar to the following:

    jar -cvf myApplication .ear myService.jar

    If you have a client .war file you can add that to the .ear file in the same way.

  2. Create a deployment descriptor application.xml either using your application server's tools or by copying and editing a sample, as follows:
    1. Locate a sample .ear, which is in examples directory in mapdemo/mapdemo/repos/myService.deploy/JMapServ-WL.ear
    2. Extract the descriptor application.xml from the .ear file, using the following jar command:
      jar -xvf JMapServ-WL.ear META-INF/application.xml
    3. Make a copy of the application.xml descriptor and edit it, replacing JMapServ with the name of your .jar file. You can also add the name of your .war file if you added that to the .ear file.
    4. Put the descriptor in the meta-inf subdirectory of the directory containing your .ear file.
    5. Package the descriptor into your .ear file using a jar command similar to:
      jar -uvf myService.ear META-INF/application.xml
Parent topic: Deploying EJBs Overview
Parent topic: Deploy to J2EE Application Servers


To Deploy to WebLogic

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. If you have not set up a WebLogic server domain, set one up using the WebLogic Domain Configuration Wizard, following the instructions in the wizard. You can start the wizard from the Start menu.
  2. If your COBOL system (either Visual COBOLor COBOL Server) is installed in a location that uses a spacey path, you need to copy the following files to a non-spacey location:
    • mfcobolpure.jar - This is by default in the $COBDIR/bin of your COBOL system installation.
    • mfconnector.jar - This is by default in a subdirectory under $COBDIR/javaee of your COBOL system installation. You need the jar file that corresponds to the WebLogic version that you are using, such as the mfconnector.jar in the javaee5/oracleweblogic10 subdirectory.
  3. Open the startup script for your project in a text editor. This startup script is StartWebLogic.sh , and is located in your domain directory of your WebLogic installation.
  4. Go to the end of the file.
  5. Above the line that starts the WebLogic server, /space/bea/weblogic7020/server/bin/startWLS.sh, add the following lines:
    JAVA_HOME=jdk_path
export JAVA_HOME
MF_HOME=mfcobolpure_path
export MF_HOME
CLASSPATH=$JAVA_HOME/lib/tools.jar:
          $MF_HOME/mfconnector_path/mfconnector.jar:
          $MF_HOME/mfcobolpure.jar
export CLASSPATH

    Where:

    • jdk_path is the location of the JDK installation to use for WebLogic.
    • mfcobolpure_path is the path containing mfcobolpure.jar.
    • mfconnector_path is the path containing the required mfconnector.jar. If you have copied this jar into the same directory as mfcobolpure.jar, you don't need to specify this path.
  6. Save the file.
  7. You can now run the startup script.

To enable tracing

To enable tracing (optional), edit the weblogic-ra.xml file that corresponds to your Java EE and WebLogic versions. The weblogic-ra.xml is included in the mfcobol-notx.rar archive file located by default in one of the following directories:
Java EE 5, WebLogic 10
/opt/microfocus/VisualCOBOL/javaee/javaee5/oracleweblogic10
Java EE 6, WebLogic 1211
/opt/microfocus/VisualCOBOL/javaee/javaee6/oracleweblogic1211
Set the following attribute to true:
  • trace

To start WebLogic

  1. Set up a WebLogic server domain and edit the startup script, if you have not already done so.
  2. Change directory to your WebLogic server domain directory.
  3. As root user, run the startup script by typing:
    startWebLogic.sh

To start WebLogic server console:

  1. Start WebLogic.
  2. Open a browser.
  3. Enter the URL, http://localhost:7001/console where 7001 is the default port for the server console.

To deploy a resource adapter to WebLogic

  1. Start WebLogic server and the WebLogic Server Console.
  2. In the left pane of WebLogic Server Console, expand your-domain >Deployments>Connectors
  3. Click Configure a new Connector Component and follow the steps on the page. When you are asked to upload the resource adapter file, upload the required mfcobol*.rar file.

    The resource adapter must be deployed on a machine where your COBOL system (either Visual COBOLor COBOL Server) is installed.

    You do not need to create a connection factory or specify the JNDI name of the resource adapter because these are already specified in the deployment descriptor for the connection factory, weblogic-ra.xml

  4. Confirm that the resource adapter has been successfully deployed, by examining the Deployment Activity table on the page on the right. The resource adapter should also be listed in the hierarchy on the left.
Note: To deploy the local transaction connector (mfcobol-localtx.rar), first deploy the XA transaction connector (mfcobol-xa.rar) and then undeploy it. You will then be able to install the local transaction connector.

To deploy an EJB to WebLogic

  1. If you don't have a .ear file containing your EJB, package the EJB into an.ear file now. You will have an .ear file if you generated a client and EJB together, and it will be in myProject/repos/myservice.deploy
  2. Start WebLogic server and the WebLogic Server Console.
  3. Deploy the .ear file as follows:
    1. In the left pane expand mydomain >Control> myserver
    2. Click Configure a new Application on the right, and follow the steps on the page.
    3. Confirm that the application has been successfully deployed, by examining the Deployment Activity table on the page on the right. The application should also be listed in the hierarchy on the left

To stop WebLogic

  1. Start the WebLogic server console, if it is not already started.
  2. Navigate to your server in the left-hand pane. This will probably mean expanding: mydomain >Control> myserver
  3. Right-click your server.
  4. Click Start/Stop server and follow the instructions.

TheWebLogic Server Console will not be available until you restart the server.

Parent topic: Deploying EJBs Overview
Parent topic: Deploy to J2EE Application Servers


To Deploy to WebSphere

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To enable tracing

Before starting WebSphere, you can optionally configure it to enable tracing. Do this in WebSphere by adding trace to the custom properties on the Resource Adapters > Micro Focus Cobol Adapter (NoTx) > J2C connection factories > CCIMFCobol_v1.5 < Custom properties page. See your WebSphere documentation for details.

To start WebSphere server

  1. Log in as WebSphere administrator. See the WebSphere documentation.
  2. Run the startup script by entering the following command from the bin directory of your WebSphere installation:
    startserver.sh myServer

To start WebSphere administrative console

  1. Start WebSphere server and WebSphere Administrative Console.
  2. In the left pane click Resources > Resource Adapters
  3. Click Install RAR on the page on the right, and follow the instructions on the screen.

    When you are asked for the resource adapter file, specify the required mfcobol*.rar file.

  4. The new resource adapter is now listed on the right. Click it to display its properties.
  5. Add a connection factory for the resource adapter. You might need to scroll to Additional Properties at the end and then click J2C Connection Factories. Then click New and follow the instructions on the screen to specify:
    • CCIMFCobol_v1.5 as the reference name for the connection factory
    • eis/MFCobol_v1.5 as the JNDI name for the connection factory
  6. Confirm that the new resource adapter is now listed on the right.
Note: The resource adapter must be deployed on a machine where your COBOL development system is installed.

To deploy an EJB to WebSphere

  1. If you don't have an .ear file containing your EJB, package the EJB into an .ear file now. You will have a. ear if you generated a client and EJB together, and it will be in myProject/repos/myservice.deploy.
  2. Start WebSphere server and WebSphere Administrative Console.
  3. In the Administrative Console, click ApplicationsInstall New Application on the left
  4. Follow the instructions on the screen. Most of the information will default to information in the generated deployment descriptors and you do not need to change it. You will however need to specify the following:
    Path to ear file
    Specify the path to your .ear file
    Deploy EJBs
    Check this
    JNDI name of EJB
    Specify any name you like, but it must match the JNDI name that other components of your application use when they refer your EJB
    Map EJB ref to an enterprise bean
    Specify the same JNDI name that you specified above

To stop WebSphere server

Either stop the server from the Start menu or:

  • Run the stop script by entering the following command from the bin directory of your WebSphere installation:
    stopserver myserver
Parent topic: Deploying EJBs Overview
Parent topic: Deploy to J2EE Application Servers


To Deploy to JBoss

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Installing JBoss Application Server

You can download JBoss Application Server from http://www.jboss.com, and install it from there.

To open JBoss Application Server:

  • Enter the URL http://localhost:8080 in your Web browser, where 8080 is the default port.

Administering JBoss Application Server

JBoss Application Server provides a Web interface for administering the application server. This administration interface is called the JBoss console. To start the console:

  • Enter http://localhost:8080/jmx-console/ in your Web browser, where 8080 is the default port.

Setting up JBoss Application Server

The JBoss Application Server provides deployment descriptors. The deployment descriptors require some changes before generating EJBs. These changes are described below, in which JBOSS_HOME is the top-level directory of your JBoss installation, and default is the location of the default server configuration in your JBoss installation.

For JBoss 5.1.0, change the following:

  • In JBOSS_HOME/server/default/conf/jboss-service.xml set the following attribute to true:
    • CallByValue
  • In JBOSS_HOME/server/default/deployers/ear-deployer-jboss-beans.xml change the following attributes:
    • Isolated - set to false
    • CallByValue - set to true
  • In JBOSS_HOME/server/default/deployers/ejb-deployer-jboss-beans.xml set the following attribute to true:
    • CallByValue
  • In JBOSS_HOME/server/default/deployers/jboss-web.deployer/META-INF/war-deployers-jboss-beans.xml set the following attribute to true:
    • Java2ClassLoadingCompliance
  • To enable tracing (optional), edit the jboss-ra.xml file, which is included in the mfcobol-notx.rar archive file located by default in /opt/microfocus/VisualCOBOL/javaee/javaee5/jboss5. Set the following attribute to true:
    • trace

For JBoss 6.1.0, change the following:

  • In JBOSS_HOME/server/default/deploy/jnaming-jboss-beans.xml set the following attribute to true:
    • CallByValue
  • In JBOSS_HOME/server/default/deployers/ear-deployer-jboss-beans.xml change the following attributes:
    • Isolated - set to false
    • CallByValue - set to true
  • In JBOSS_HOME/server/default/deployers/ejb-deployer-jboss-beans.xml set the following attribute to true:
    • CallByValue
  • In JBOSS_HOME/server/default/deployers/jboss-web.deployer/META-INF/war-deployers-jboss-beans.xml set the following attribute to true:
    • Java2ClassLoadingCompliance
  • To enable tracing (optional), edit the jboss-ra.xml file, which is included in the mfcobol-notx.rar archive file located by default in /opt/microfocus/VisualCOBOL/javaee/javaee6/jboss6. Set the following attribute to true:
    • trace

Starting and Stopping JBoss Application Server

You can start and stop JBoss Application Server from the JBoss console or from the command line, as follows.

:

:

  • Run jboss_home/bin/run.bat to start it.
  • Run jboss_home/bin/shutdown.bat -S to stop it.

Deploying the Resource Adapter

Resource adapters, named mfcobol*.rar, are supplied together with JBoss-specific deployment descriptors for using the resource adapters with the JBoss Application Server. The descriptors have names corresponding to the resource adapters, as follows:

  • mfcobol-notx-ds.xml is the desciptor for the resource adapter mfcobol-notx.rar
  • mfcobol-localtx-ds.xml is for mfcobol-localtx.rar
  • mfcobol-xa-ds.xml is for mfcobol-xa.rar

To deploy a resource adapter:

  1. Copy the appropriate .rar file into your JBoss deployment directory, which is by default jboss_home/server/default/deploy
  2. Copy the corresponding deployment descriptor,*ds.xml , for the resource adapter into the same directory. For example, if you are deploying mfcobol-notx.rar, copy mfcobol-notx-ds.xml.

Deploying the Application .ear File

When you generate an application .ear file the JBoss Application Server requires that the .ear file contains deployment descriptors that specify deployment information about your application. When you use generate a client and EJB using the Interface Mapping Toolkit, these deployment descriptors are automatically created and packaged into the .ear.

To deploy your application .ear file:

  1. Copy the application .ear file from the directory my-project/repos/my-service.deploy/my-service.ear into your JBoss deployment directory which is, by default, jboss_home/server/default/deploy

Logging

JBoss stores log files and traces by default in jboss_home\server\default\log\server.log

Configuring a JDBC Data Source for XA Transactions

If the application being deployed connects to a third party database, you will need to configure a JDBC data source and specify information such as the JNDI name of the data source. For an Oracle database, you edit the Oracle-supplied deployment descriptor oracle-xa-ds.xml. For full details see the JBoss administration documentation on configuring JDBC data sources.

Further Information

For further information, see the Release Notes for your JBoss Application Server installation and the JBoss Web site.

Parent topic: Deploying EJBs Overview
Parent topic: Deploy to J2EE Application Servers


Resource Adapters Supplied by Micro Focus

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Micro Focus resource adapters enable EJBs deployed on J2EE to communicate with COBOL on an enterprise server. Resource adapters are also known loosely as J2EE connectors.

Before an EJB can communicate with the COBOL code running on an enterprise server, you need to:

  • Deploy a resource adapter to the J2EE application server. Only one resource adapter can be deployed at a time. This resource adapter then handles all the binary requests being sent to the enterprise server.

    You must deploy a resource adapter appropriate to your application server and the J2EE version it uses. The following resource adapters are supplied for each supported application server and J2EE version:

    • mfcobol-notx.rar - does not support transactions
    • mfcobol-localtx.rar - supports local transactions
    • mfcobol-xa.rar - supports XA transactions
  • Ensure that support for the resource adapter is available, by adding the archive files mfcobolpure.jar and mfconnector.jar to your classpath environment variable. Again, you must add support for the resource adapter appropriate to your application server and the J2EE version it uses.

The information needed to deploy the resource adapters is set up in deployment descriptors.

  • To Add Support for Micro Focus Resource Adapters
  • To Deploy a Micro Focus Resource Adapter to a J2EE Application Server
Parent topic: Deploying EJBs and Resource Adapters
Related information
To add support for Micro Focus resource adapters
To deploy a Micro Focus resource adapter to a J2EE application server
Deployment Descriptors that Are Required


To Add Support for Micro Focus Resource Adapters

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Edit the classpath to point to the archive files mfcobolpure.jar and mfconnector.jar, which contain the classes that support for the Micro Focus resource adapters.

    To do this, use the command:

    CLASSPATH=$COBDIR/lib/mfcobolpure.jar:jar_path/mfconnector.jar:$classpath

    where jar_path is the path to the archive files appropriate to your application server.

    Specific versions of these files are supplied for each supported application server and J2EE version. They are available in the application server subdirectories under $COBDIR/javaee in your COBOL system installation or on the CD or DVD, as follows:

    • javaee5/ibmwebsphere7
    • javaee5/jboss5
    • javaee5/oracleweblogic10
    • javaee6/ibmwebsphere8
    • javaee6/ibmwebsphere85
    • javaee6/jboss6
    • javaee6/oracleweblogic1211
Parent topic: Resource Adapters Supplied by Micro Focus
Parent topic: Deploy to J2EE Application Servers


To Deploy a Micro Focus Resource Adapter to a J2EE Application Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Start your J2EE application server and its administration console, and navigate to where you add resource adapters.

    The resource adapter must be deployed on a machine where a COBOL system such as COBOL Server or Visual COBOL is installed.

  2. Specify the resource adapter to deploy. These can be one of the following:
    • mfcobol-notx.rar - does not support transactions
    • mfcobol-localtx.rar - supports local transactions
    • mfcobol-xa.rar - supports XA transactions

    Specific versions of these files are supplied for each supported application server and J2EE version. They are available in the application server subdirectories under $COBDIR/javaee in your COBOL development system, as follows:

    • javaee5/ibmwebsphere7
    • javaee5/jboss5
    • javaee5/oracleweblogic10
    • javaee6/ibmwebsphere8
    • javaee6/ibmwebsphere85
    • javaee6/jboss6
    • javaee6/oracleweblogic1211
  3. Ensure that the support for the resource adapters and ensure it is on your path and classpath environment variables.
  4. You might need to provide the application server with a deployment descriptor for the resource adapter. Deployment descriptors are supplied for the following application servers:
    • JBoss - mfcobol*ds.xml, which are supplied in the folder with the .rar files
    • WebLogic - weblogic-ra.xml, which is packaged in each .rar file
    • WebSphere - does not require deployment descriptors

    Among other things, the deployment descriptors specify the following connection information, and you must not change this.

    Note: The JNDI name and the reference name that you enter both depend upon your J2EE version.
    JNDI name | Reference name
    Java EE 5 | eis\MFCobol_v1.5 | CCIMFCobol_v1.5
    Java EE 6 | eis\MFCobol_v1.5 | CCIMFCobol_v1.5
    Note: The resource adapter must be deployed on a machine where either Micro Focus Server or your COBOL development system is installed.
Parent topic: Resource Adapters Supplied by Micro Focus
Parent topic: Deploy to J2EE Application Servers


Deployment Descriptors that Are Required

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Deployment descriptors are xml files that describe the component to be deployed. J2EE application servers require deployment descriptors for the archive files (.jar, .war and .ear) to be deployed. At run time, the application server reads the descriptors and acts accordingly.

When you generate an EJB or client using the COBOL development system Visual COBOL, generic deployment descriptors are created and they are packaged into the relevant archive files. Some J2EE application servers require additional deployment descriptors and these are generated automatically for the supported application servers.

If your application server requires additional deployment descriptors and these are not generated, you need to create them manually and add them to the archive files. In many cases, you can create deployment descriptors using the administration console for your application server. Alternatively you can edit them in a text editor.

For example, the deployment descriptor weblogic-ra.xml, which is in the archive file mfcobol-notx.rar, contains the following lines:

<connection-factory-name>CCIMFCobol_ver</connection-factory-name>
<jndi-name>eis/MFCobol_ver</jndi-name>

Where ver is v1.5 for javaee5

  • To Create Deployment Descriptors Manually
Parent topic: Deploying EJBs and Resource Adapters
To create deployment descriptors manually


To Create Deployment Descriptors Manually

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can create deployment descriptors using the administration tool provided by your J2EE application server. You need to specify the following information in the deployment descriptor:

  • The JNDI name of the EJB. This can be any name you like, but it must match the JNDI name that other components of your application use when they refer your EJB.
  • The JNDI name and resource reference name of the Micro Focus resource adapter.

    Among other things, the deployment descriptors specify the following connection information, and you must not change this.

    Note: The JNDI name and the reference name that you enter both depend upon your J2EE version.
    JNDI name | Reference name
    J2EE 1.3 | eis\MFCobol_v1.0 | CCIMFCobol_v1.0
    J2EE 1.4 | eis\MFCobol_v1.5 | CCIMFCobol_v1.5
    Java EE 5 | eis\MFCobol_v1.5 | CCIMFCobol_v1.5
    Java EE 6 | eis\MFCobol_v1.5 | CCIMFCobol_v1.5

Note that deployment descriptors are automatically created for the supported application servers that are listed in Servers > Settings on the EJB Generation tab in the Application server field.

Parent topic: Deployment Descriptors that Are Required
Parent topic: Deploy to J2EE Application Servers
Related information
EJBs and Resource Adapters


CustomRecord and the RuntimeProperties Support

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Support for the CustomRecord and the RuntimeProperties interfaces is provided in mfejblib.jar for EJBs and in mfj2se.jar for J2SE Java beans.

For J2SE Java beans, you need to make sure that the mfj2se.jar is available to the Java run-time system and is on the Java classpath.

For EJBs, this support is automatically included in the application .ear file when you generate a client for the EJB. If you create a client manually, you need to add the mfejblib.jar to your .ear file, manually. Specific versions of this file are supplied for each supported application server and J2EE version.

Parent topic: Deploying EJBs and Resource Adapters


Third Party Application Server Deployment

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Several third party application servers are supported for use during development and in production. For example WebSphere and WebLogic.

Most third party application servers come with a Web-based administration console, which you use to deploy EJB and resource adapters. These take you step by step through deployment and provide information online.

When you have changed the modules deployed on the server, we recommend that you stop and restart the server.

Parent topic: Deploying EJBs and Resource Adapters
Related information
To deploy a Micro Focus resource adapter to a J2EE application server
To add support for Micro Focus resource adapters
To create deployment descriptors manually
To create an .ear file for your EJB
To deploy to WebLogic
To deploy to WebSphere
To deploy to JBoss


Troubleshooting

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your deployed EJB does not work, check the following things:

  • Have you stopped and restarted the application server? Sometimes this is required to pick up changes to deployments and configuration. Whenever you reboot the WebLogic machine, you also need to restart the WebLogic server from the Start menu.
  • Is the enterprise server you require running?
  • Are the required services deployed to the enterprise server? Were they deployed successfully? You can check this by looking in the Enterprise Server Administration console, http://locahost:86, in deploy/.../deploylog.txt and $COBDIR/var/mfcobol/es/WORKAREA/esname/console.log, where esname is your enterprise server name, such as ESDEMO.
  • Was any information written to the resource adapter log file cobcon.log? This log file is located in the directory defined in your Java system's user.home property. This directory equates by default to your user profile directory. If there wasn't any information written to the log file, the failure occurred before the resource adapter was invoked. The failure might lie in the application server setup. Notice that there are backup log files cobcon1.log and cobcon2.log.
  • Was any information written to the communications server log file log.html? See the section Communications Server Log Files in the Troubleshooting chapter.
  • When you generated your EJB using the Deploy tool, did you use the J2EE connector classes specific to your application server? For example, you must use WebLogic.jar for WebLogic EJB generation and j2ee.jar for WebSphere EJB generation. You specify these classes in the Classpath settings of the Deploy tool.
  • Is the JNDI name of the resource adapter set to the respective eis/MFCobol_v1.n as specified in the topic To Deploy a Micro Focus Resource Adapter to a J2EE Application Server? Is this JNDI name mapped to the resource references of the EJB.
  • Is the JNDI name for each EJB the same wherever it is referred to? When you assign a JNDI name to an EJB, any client or other software that uses that EJB must use that same JNDI name.
  • Are the EJB and the resource adapter successfully deployed in your application server?
  • What failures are recorded in your application server's log files? All the supported application servers have a logs subdirectory.
Parent topic: Deploying EJBs and Resource Adapters
Related information
Communications Process Log Files
To deploy a Micro Focus resource adapter to a J2EE application server


Enterprise Server Task Index

Restriction: This topic applies only when the Enterprise Server feature is enabled.

  • Accessing the Enterprise Server Administration UI
  • Accessing the ESMAC User Interface
  • Administer a Server Using ESMAC
  • Configure the Directory Server
  • Deploy Service Interfaces to Enterprise Server
    Tasks related to deploying service interfaces to Enterprise Server.
  • Deploy to J2EE Application Servers
  • Log On and Off
  • Monitor Directory Server
  • Start and Stop the Directory Server
  • Work with Communication Processes and Service Listeners
  • Work with Packages
  • Work with Request Handlers
  • Work with Servers
  • Work with Services
  • Work with the Directory Server Repository
Parent topic: Enterprise Server


Accessing the ESMAC User Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You use the Enterprise Server Monitoring and Control (ESMAC) user interface to monitor and control the enterprise server instances that your installation is running. From the ESMAC user interface, you can monitor and control all aspects of each enterprise server instance.

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details..

    The Details screen for the server is displayed.

  4. On the Details screen, click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

Parent topic: Enterprise Server Task Index


Administer a Server Using ESMAC

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Change the Trace Dataset
  • To Configure Dumps
  • To Create an ESMAC User
  • To initiate a system dump
  • To stop or kill a SEP
  • To Monitor Services
  • To Record Service Input and Output
  • To specify what information is traced
  • To Start ESMAC for an enterprise server instance
  • To Transfer the In-memory Trace Data to the Auxiliary Dataset at Rollover
  • To View a Dump
  • To View a Local Trace for a Client Process
  • To View a Local Trace for a SEP
  • To View a System Trace
Parent topic: Enterprise Server Task Index


To Create an ESMAC User

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: This procedure is supported for backward compatibility only.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To create an ESMAC user:

  1. Click Users.

    The Users page is displayed

  2. Click New.

    The CICS SNT page is displayed.

  3. In the field Name, enter the name to be used by this user when logging in.
  4. Optionally, you can enter a short description for the user; enter it in the field Description.
  5. In the field Password, enter a password for the user.
  6. In the field Repeat PW, re-enter the password. This ensures that you type the password correctly.
  7. If you want the password always to be entered in upper case, check Upper case.
  8. In the field Operator ID, enter an operator ID for this user. This is optional.
  9. In the field Timeout, enter a timeout period, in minutes, for this user. This is optional.

    If the user does not interact with ESMAC for more minutes than defined in this field, security permissions revert to the default permissions.

  10. To set what aspects of a server and its definitions a user can change:
    1. Check Yes in the Definition Access group
    2. Click on the required dropdown, and select one of:
      • No - the user cannot read or update the selected definition
      • Upd - the user can read and update the selected definition
      • Rd - the user can read the selected definition

    By default, the user cannot read or update definitions; that is, the Definition Access, Yes check box is unchecked, and all definitions are set to No.

    If you set the definitions to Rd or Upd, these only have an effect if the Definition Access, Yes check box is checked.

    To set all definitions to No, Upd or Rd, click the all dropdown and select No, Rd or Upd, respectively.

  11. Click Add.

    The user is added to the list of users. The CICS SNT page is redisplayed, enabling you to change any details for this user.

Note:

You can ignore the controls Group prefix, Oper Class, and those for resource keys, security keys, and surrogate security keys.

Parent topic: Administer a Server Using ESMAC
Related information
To start ESMAC for a server
To monitor services
To configure dumps
To view a dump
To initiate a system dump
To specify what information is traced
To change the trace dataset
To transfer the in-memory trace data to the auxiliary dataset at rollover
To view a system trace
To record service input and output
To view a local trace for a SEP
To view a local trace for a client process
To kill a SEP
To reply to an ACCEPT FROM CONSOLE statement
To shut down a server


To stop or kill a SEP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can stop or kill a service execution process (SEP).

If you stop a SEP it will stop when the SEP has completed the current task. Stopping a SEP is most useful if t is a SEP with a debugger attached.

Killing stops the SEP when it is currently running a task. If the task terminates prior to the kill process being initiated, ESMAC returns a message explaining that the target task was no longer active.

Note: After stopping a process, Enterprise Server will automatically replace the SEP to keep the configured number of SEPs - unless it is a debug SEP or a SEP that was started from the command prompt. In these cases it will stop the SEP but not replace it.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To stop or kill a SEP

  1. Click SEPs in the menu.
  2. Click Stop next to the SEP.

To kill a SEP

  1. Click SEPs in the menu.
  2. Click Kill next to the SEP.
Parent topic: Administer a Server Using ESMAC
Related information
To shut down a server
To view a local trace for a SEP


To Transfer the In-memory Trace Data to the Auxiliary Dataset at Rollover

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To start ESMAC:

  1. Access the Enterprise Server Administration screen for your installation.
  2. In the table of enterprise server instances, check that the server you want has started, and if not, start it.
  3. In the Status column of the enterprise server instance to monitor, click Details.

    The Details screen for the server is displayed.

  4. On the Details screen, select the Server > Control tab, then click ES Monitor & Control.

    The Enterprise Server Monitoring and Control (ESMAC) screen is displayed.

To transfer the in-memory trace data to the auxiliary dataset at rollover

  1. Click Control.

    The Control page is displayed.

  2. Check Active Trace DS, active
Note:

By default, the enterprise server uses the A dataset to record trace information.

Parent topic: Administer a Server Using ESMAC


Configure the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Configure the MF Directory Server
  • To Run casperm
Parent topic: Enterprise Server Task Index


To Configure the MF Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Configure > Options on the menu on the left-hand side of any Enterprise Server Administration Web page.
  2. Update the attributes of the Directory Server as required.
  3. Click OK.
Note:

If you check Restricted under User Access, as soon as you click Apply you will be asked for a valid user ID and password with at least Administrator permission level, which you must provide to continue working.

Parent topic: Configure the Directory Server


To Run casperm

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Log in as root.
  2. Set COBDIR to the location of the installed product.
  3. Enter:
    casperm.sh

    You see a message asking you to ensure you have the alphanumeric user ID of the Enterprise Server System Administrator to hand. This becomes the Process User ID.

    You then see the message:

    Do you want Error and Warning messages to be displayed via the syslog daemon (y/n)?

    The console messages are always directed to the file console.log. Responding Y to this prompt will also direct them to the syslog daemon as Info type messages.

  4. Enter Y or N.

    You then see the message:

    Enter the alphanumeric user ID of the Enterprise Server System Administrator.
    Press return to use (hub):

    This is the user id which will be the owner of all Enterprise Server processes with the exception of the Directory Server, which must run as root. It is known as the Process User ID. When an enterprise server is started from the Administration Server Administration it will run under this user ID. Since all the server's processes will run with this user's authority this has implications for file creation and access. The Directory Server has to run as root because the Directory Server process (Enterprise Server Administration) uses port 86. This port is only accessible to processes running with root authority.

  5. Enter the Process User ID or press Enter to use the default value.

    You then see the message:

    Enter the directory where you want the Enterprise Server
 run-time system files to reside. Please enter the absolute path.
 Do not use environment variables. Press return to use (/var/mfcobol/es):

    You should take the default unless you have a good reason not to.

    The directory given here will be the root for the working directory for all enterprise servers run in this installation. A new directory will be created for each server the first time it is run and a number of files will be created in this location including the console.log file and diagnostics files. It is imperative that the Process User ID has create and write permissions in this directory.

  6. Press Enter to accept the default or enter the directory you want to use.

    The script executes and processes the settings you entered above. Once complete, it displays the following message:

    Processing –f option...

    Then the command terminates.

Parent topic: Configure the Directory Server


Deploy Service Interfaces to Enterprise Server

Tasks related to deploying service interfaces to Enterprise Server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To add or remove application files to deploy
  • To associate an enterprise server with a project
  • To generate and deploy a service interface from the IDE
  • To deploy to a remote enterprise server
  • To generate and deploy a service interface using imtkmake
  • To generate clients
  • To install a deployment package using the mfdepinst command
  • To redeploy a service interface
  • To set deployment properties
Parent topic: Enterprise Server Task Index


To set deployment properties

  1. From the , right-click a service interface; then click Properties.
  2. Modify property settings as required. For complete information on each property, see Properties - Service Interface.
Parent topic: Deploy Service Interfaces to Enterprise Server


Deploy to J2EE Application Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Deploy to WebSphere
  • To Deploy to WebLogic
  • To Deploy to JBoss
  • To Create Deployment Descriptors Manually
  • To Create an .ear File for your EJB
  • To Add Micro Focus Support for EJBs
  • To Add Support for Micro Focus Resource Adapters
  • To Deploy a Micro Focus Resource Adapter to a J2EE Application Server
Parent topic: Enterprise Server Task Index


Log On and Off

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Log On to Enterprise Server Administration
  • To Log Off from Enterprise Server Administration
Parent topic: Enterprise Server Task Index


Monitor Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To View the Sessions List
  • To View the Journal
  • To View and Use Remote Directory Server Instances
  • To View Directory Server Statistics
  • To export the journal as a text file
  • To Delete Journal Entries
  • To Configure Run-time Core Dumps
Parent topic: Enterprise Server Task Index


Start and Stop the Directory Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Start the Directory Server from the Command Line
  • To Stop the Directory Server
Parent topic: Enterprise Server Task Index


Work with Communication Processes and Service Listeners

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Add a Service Listener to an Enterprise Server Instance
  • To Associate a Listener with a Service
  • To Start a Communications Process
  • To Stop a Communications Process
  • To Copy a Communications Process
  • To Edit a Communications Process
  • To Delete a Communications Process
  • To Start a Listener
  • To Stop a Listener
  • To Edit a Listener
  • To Disassociate a Listener from a Service
  • To delete a listener
  • To View Communications Processes and Listeners for an Enterprise Server Instance
  • To View Statistics for a Communications Process
Parent topic: Enterprise Server Task Index


Work with Packages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Add a Package to an Enterprise Server Instance
  • To Edit a Package
  • To Associate a Package with a Service
  • To Disassociate a Package from a Service
  • To View Packages for an Enterprise Server Instance
  • To Delete a Package
  • To Delete Old Deployed Package Files
Parent topic: Enterprise Server Task Index


Work with Request Handlers

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Add a Request Handler to an Enterprise Server Instance
  • To Edit a Request Handler
  • To Associate a Request Handler with a Service
  • To Disassociate a Request Handler from a Service
  • To View Request Handlers for an Enterprise Server Instance
  • To Delete a Request Handler
Parent topic: Enterprise Server Task Index


Work with Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Add an Enterprise Server Instance
  • To Add an XA Resource
  • To Change the Number of ES licenses
  • To Change the Number of SEPs
  • To Copy an Enterprise Server Instance
  • To Create and View a Diagnostic Dump for an Enterprise Server Instance
  • To Delete an Enterprise Server Instance
  • To Delete an XA Resource
  • To Delete a CCI Server
  • To Edit an Enterprise Server Instance
  • To Edit an XA Resource
  • To Enable or Disable an XA Resource
  • To start an enterprise server instance
  • To stop a server Instance
  • To View the Communications Console Log for an Enterprise Server Instance
  • To View the Enterprise Server Log Files
  • To View the Control Page for an Enterprise Server Instance
Parent topic: Enterprise Server Task Index


To Create and View a Diagnostic Dump for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Home page click Edit to the left of the server whose console log you want to view.
  2. Click the Diagnostics tab.
  3. Click the Dump tab.
  4. Click Create Dump.

    The page is refreshed showing a table of dumps with one row for the dump you just created.

    Note:

    Create Dump is only available when the server is started.

  5. Click Show against the dump you just created. You briefly see a console window, then the dump file overwrites the contents of the Dump page.
  6. When you have finished viewing the dump, click Datasets to return to the Server > Diagnostics > Dump page.
Parent topic: Work with Servers


To View the Communications Console Log for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the Enterprise Server Administration Home page click Edit to the left of the server whose communications console log you want to view.
  2. Click the Diagnostics tab.
  3. Click the CS Console tab.
  4. To view the entire log since the server was started, click Show Entire Log. The log opens in a new Web browser window. To return to ESMAC, click Back in your browser.
Parent topic: Work with Servers


To View the Control Page for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • In the Enterprise Server Administration screen, click Details in the Current status column of the enterprise server instance you want.
    Note:

    You can click Details only if the status of the Server is "Started".

Parent topic: Work with Servers


Work with Services

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To View Services for an Enterprise Server Instance
  • To Add a Service to an Enterprise Server Instance
  • To Edit a Service
  • To Change the Status of a Service
  • To Switch Logging On for a Service
  • To Add a Service for Integration with the Micro Focus Development Tools
  • To Delete a Service with Operations
  • To Delete a Simple Service or an Operation
Parent topic: Enterprise Server Task Index


Work with the Directory Server Repository

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • To Import a Repository
  • To Export the Repository
  • To Restore the Repository
  • To Delete the Repository
Parent topic: Enterprise Server Task Index


Enterprise Server Reference

Restriction: This topic applies only when the Enterprise Server feature is enabled.

  • Administration and Configuration Commands
  • Error Messages
  • User Exits
Parent topic: Enterprise Server


Administration and Configuration Commands

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following commands are available for performing Enterprise Server administration procedures.

  • casdump
    Forces a system dump.
  • casdup
    Formats a system dump or auxiliary trace so that it is suitable for analysis.
  • casperm.sh
    Prepares Enterprise Server for use.
  • casstart
    Starts an enterprise server.
  • casstop
    Stops an enterprise server.
  • mfdepinst command
    Installs the service interface contained in deployment package (.car) file to an enterprise server instance.
  • imtkmake command
    Enables you to create and deploy a COBOL program-based service interface, and generate a client to access the deployed service running on an enterprise server.
  • mfds
    Manages the Directory Server.
  • mfpackage
    This utility is used for maintaining services and packages installed on an enterprise server. Its function is to delete all services and packages in a given namespace for a given enterprise server region, and is equivalent to deleting the services and packages using the Micro Focus Administration Console (MFDS). It can also be used to prepare the server before deploying a new version of the service..
Parent topic: Enterprise Server Reference


mfdepinst command

Installs the service interface contained in deployment package (.car) file to an enterprise server instance.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The mfdepinst command handles the server-side part of the process of deploying a service to enterprise server. The tool installs the files contained in a .car to an enterprise server instance by extracting the deployment package files (.int, .idt, .etc) from the .car file, updating the Directory Service directory for the new services and packages, and if the enterprise server is running, informs it of the new services so they are available for use.

Syntax:

mfdepinst myservice.car

Parameters:

myservice.car
The name of the .car file containing the service to be deployed.

Dependencies:

Before running mfdepinst, copy the .mfdeploy file in the $COBDIR/deploy to the parent directory of the directory that contains the .car file.

.mfdeploy specifies the location, name, and listener for the enterprise server to which the service interface is deployed. So, for example, if the .car file is in $COBDIR/myservice/myservice.deploy , the .mfdeploy file must be in $COBDIR/myservice.

Edit .mfdeploy as necessary to specify values other than the default values.

Run mfdepinst from aVisual COBOL command prompt from the same directory that contains the .car file.

Comments:

mfdepinst extracts files from the .car file and installs them on the enterprise server specified in the .mfdeploy file.

mfdepinst records its progress in the file deploylog.txt in the current directory, overwriting any existing deploylog.txt. After mfdepinst completes, you can examine this file to find out if deployment succeeded.

Parent topic: Administration and Configuration Commands


imtkmake command

Enables you to create and deploy a COBOL program-based service interface, and generate a client to access the deployed service running on an enterprise server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

imtkmake -defmap          service=service-name
                          src=program-name
                          type=service-type
                         [directives=Compiler-directives]
                         [settings=properties-filename]

imtkmake -generate        service=service-name
                          type=service-type
                         [appdir=directory-name]
                         [appserver=J2EE-application-server-name]
                         [bean=bean-name]
                         [classpath=pathname]
                         [ejbname=ejb-name]
                         [esruntime=esruntime-filename]
                         [exithandler=program-name]
                         [filename]...
                         [@filelistname]
                         [jarname=jar-filename]
                         [namespace=service-namespace]
                         [package=package-name]
                         [sepsession={stateless|stateful}]
                         [serverHost=host-name]
                         [serverPort=port-number]
                         [session={stateless|stateful}]
                         [settings=properties-filename]
                         [style={doclit|rpcenc}]
                         [transaction={application|container}]
                         [transactional={yes|no}]
                         [url=ip-address]

imtkmake -query
imtkmake -queryAppServerList
imtkmake -deploy          type=service-type
                         [carname=car-filename]
                         [password=secure-password]
                         [server=server-name,deployer-name]
                         [settings=properties-filename]
                         [username=secure-username]

imtkmake -showlog         deploydir=deployment-directory
imtkmake -genclient       service=service-name
                          type=service-type
                         [appserver=J2EE-application-server-name]
                         [clientdir=directory-name]
                         [j2eeVersion={1.4|1.5|5|1.6|6}]
                         [namespace=service-namespace]
                         [style={doclit|rpcenc}]
                         [url=ip-address]
imtkmake -genclientwsdl   clientwsdl=wsdl-filename
                         [clientdir=directory-name]
                         [defaultstringsize=string-size]
                         [defaultarraysize=array-size]
imtkmake -help

Parameters:

-defmap
Create a service interface using default mappings based on the COBOL program specified in the src= parameter.
-generate
Generate deployment files based on the parameters set, and generate a COBOL archive (.car) file containing the generated files for deployment to the enterprise server.
-query
List the enterprise servers available for deployment.
-queryAppServerList
List the available J2EE 1.4 application servers by default. Specify the j2eeversion parameter to see application servers supported for other J2EE versions.
-deploy
Deploy the .car file created with -generate parameter to the enterprise server. Execute imtkmake with the -deploy parameter from the servicename.deploy directory.
-showlog
Display the contents of the deployment log (deploylog.txt file).
-genclient
Generate a client from the service interface, according to the specified type, such as EJB or Web Services.
Note: When specifying J2EEversion, the values 1.5 and 5 are equivalent, and the values 1.6 and 6 are also equivalent.
-genclientwsdl
Generate a COBOL client from WSDL.
-help
Display information about imtkmake functions and parameters.
appdir=directory-name
The path to the application files for the application running on the enterprise server.
appserver=J2EE-application-server-name
This is the name and version of the J2EE application server for which an EJB is generated and to which an EJB is deployed. This defines the deployment descriptors that are generated.

This is mandatory when generating EJBs and EJB clients. In other words, mandatory when using the -generate or -genclient functions with type set to EJB. The values must be within quotes since they contain spaces. For example:

  • "JBoss 5.1.0"
  • "WebSphere 7.0"

Note that this parameter must come after the other parameters.

See -queryAppServerList for how to list the available servers.

bean=bean-name
For EJB generation, the name of the bean to generate. Defaults to service-name.
carname=car-filename
The path to and name of the .car file to deploy. By default, this file is named service.car and is in the service.deploy directory. carname= is not required when you generate and deploy on the same command line.
classpath=pathname
For EJB generation, the classpath of the J2EE implementation classes on the J2EE application server. This is case sensitive. This is different for each J2EE application server and is the path to the following .jar files:
  • JBoss's jboss-j2ee.jar and servlet-api.jar
  • WebSphere's j2ee.jar
  • WebLogic's weblogic.jar
clientdir=directory-name
The directory in which to generate the client program. With the -genclientwsdl function, defaults to the WSDL file directory; otherwise defaults to the directory where the service is deployed
clientwsdl=wsdl-filename
The name of the WSDL file to generate the client program from which to generate it.
defaultarraysize=array-size
The default array size to use for unbounded arrays.
defaultstringsize=string-size
The default string size to use for unbounded strings.
deploydir=deployment-address
The URL of the deploylog.txt file. This URL is displayed by the -deploy function.
directives=Compiler-directives
The directives required for the program to compile correctly. Use a comma between directives.
ejbname=ejb-name
For EJB generation, the name of the EJB to generate. Defaults to service-nameEJB.
esruntime=esruntime-filename
The name of a file containing the run-time configuration settings to be applied when the deployed service is run. The file extension must be .rtc.
exithandler=program-name
For Web Services generation, the name of a user exit program to handle the exit points in the MFRHSOAP request handler.
@filelistname
The name of a file containing a list of additional files that need to be included in a .car file. Each file name must be on a new line.
filename
An additional file that needs to be included in a .car file. You can specify multiple additional files.
jarname=jar-filename
For EJB generation, the name of the .jar file to create. Defaults to service-name.jar.
namespace=service-namespace
For Web Services generation, EJB generation and client generation, the service namespace. Web Services generation and client generation defaults to http://tempuri.org/service-name. EJB generation defaults to service-name .
package=package-name
For EJB generation, the name of the package of Java classes to contain the bean. This is case-sensitive. Defaults to com.mypackage.service-name.
password=secure-password
The password to enable a service interface to be deployed to a secure server. This is required only when MFDS is configured to require it.
sepsession={stateless|stateful}
The setting for the associated SEP (Service Execution Process) attribute. SEP attributes are only meaningful when transactional=yes.
server=server-name,deployer-name
The destination of the deployment files. server-name is the enterprise server to which you want to deploy the service, and deployer-name is the name of a deployment service on that enterprise server. If you do not supply this parameter, the function lists the servers available for deployment and prompts you to choose one.
serverHost=host-name
The name of the host machine that is running the enterprise server for the J2SE Java bean.
serverPort=port-number
The port number of the enterprise server listener for the J2SE Java bean
service=service-name
The name of the service for mapping or generation.
session={stateless|stateful}
For EJB generation, the type of EJB to generate. Defaults to stateless.
settings=properties-filename
The name of a file containing the set properties for this service interface.
src=program-name
The program use for creating default mappings.
style={doclit | rpcenc}
The style to use for WSDL generation. The default is doclit.
transaction={application|container}
Specifies whether the service is application-managed or transaction-managed. The default is application.
transactional={yes|no}
For EJB generation, whether or not the EJB service executes in a transactional context. When set to yes, session=stateful by default.
type=service-type
The type of mapping to perform or type of client to generate (see defmapgenclient and generate above), where service-type can be one of the follwoing:
  • EJB
  • J2SEbean
  • WebService
url=ip-address
For Web Services and client generation, the IP address of the service. This is added to the WSDL document.
username=secure-username
The username that enables a service interface to be deployed to a secure server. This is required only when MFDS is configured to require it.

Comments:

  • Execute imtkmake from a Visual COBOL command prompt in the directory that contains your COBOL program file.
  • This command performs several functions. You must execute the following against the same program in the this order:
    • -defmap
    • -generate
    • -query (optional)
    • -deploy
    • -showlog (optional)
    • -genclient and/or -genwsdl (optional)
  • You can combine some functions on the same command line:
    • -defmap and -generate together, to create a service interface with default mappings and generate deployment files to be deployed at a later time.
    • -generate and -deploy together, to generate deployment files for an existing service interface, deploy them to an enterprise server.
    • -defmap, -generate, and -deploy together to perform all three functions.
    Note: When you combine two or more functions on the same command line, you do not need to repeat parameters that are common.
  • You can combine the use of the command line functions with the use of the Service Interfaces feature. For example, you might create the service interface and customize it. You could then use the command line to deploy the service interface.
  • If you use the Service Interfaces feature to specify mapping properties for the service interface using the Mapping Properties dialog box, Visual COBOL creates an XML file to hold the settings. You can specify this XML file to the -generate function using the settings=properties-filename parameter. The mapping properties XML file contains values for the optional parameters associated with the -generate function. If you specify any of those parameters on the command line, these override the values contained in the mapping properties XML file.
  • When you deploy a service interface using imtkmake -deploy, imtkmake looks in the following places in the following order to find items to deploy, and uses the first instance of each deployable item found:
    • MFDS. If the deployment items are in MFDS, any configuration settings in the [destination] section are used. For example:
      [destination]
   server=ESDEMO
   listener=Web Services and J2EE
    • MFDS. If the deployment itemsare in MFDS, but there aren't any configuration settings, imtkmake uses the enterprise server that owns the service.

Examples:

The following command creates a service interface with default mapping for the program book.cbl:

imtkmake -defmap src=book.cbl service=wmapserv type=webservice

The following command generates a Web service for the wmapserv service interface:

imtkmake -generate service=wmapserv
                          type=webservice
                          exithandler=myhandler
                          namespace=http://corpuri.org/wmapserv

The following command generates an EJB for the JMapServ service interface:

imtkmake -generate service=JMapServ
                          type=ejb
                          bean=JMap
                          classpath=/usr/java131/lib/j2ee.jar
                          ejbname=JMapEJB
                          esruntime=jmapconf.rtc
                          jarname=JMap.jar
                          package=com.corp.jmap
                          session=stateful
                          appserver="WebLogic 10.3.5"

The following command generates a Web service for the wmapserv service interface and deploys it to the enterprise server ESDEMO. The additional data file data-files-path/bookfile.dat is deployed:

imtkmake -generate service=wmapserv type=webservice
         -deploy server=ESDEMO,Deployer data-files-path/bookfile.dat

The following command deploys a Web service that has already been generated in wmapserv.car to the enterprise server ESDEMO:

imtkmake -deploy carname=wmapserv.car server=ESDEMO,Deployer

This submit is a successful deployment, as indicated by the 202 return code, and the presence of the URL in the response message.

The following command displays the deploylog.txt file from the URL http://10.120.72.229:47704/uploads/cw_diYLq:

imtkmake -showlog deploydir=http://10.120.72.229:47704/uploads/cw_diYLq

The following command creates a COBOL client program for the service wmapserv:

imtkmake -genclient type=webservice service=wmapserv

The following command creates a COBOL client program for the service wmapserv using the service's WSDL file:

imtkmake -genclientwsdl clientwsdl=$PWD/wmapserv.wsdl clientdir=$PWD
Parent topic: Administration and Configuration Commands


mfds

Manages the Directory Server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax for starting or stopping the Directory Server:

mfds [/d|/dn network-address|/n network-address] [/j journal-path] [/r] [/p port-number]

Syntax for stopping the Directory Server

mfds [/p port-number] -s option [username password]

Syntax for reporting and exporting information:

mfds /v
mfds /m
mfds /e root-DN user-partition-DN group-partition-DN
          resource-partition-DN schema-format ldif-filename
          sec-path
mfds /l [schema partition Distinguished Name] option ldif-filename [schema-version-1] [schema-version-2]

Syntax for exporting the currently active MFDS process repository to a specified path:

mfds -x [repository type] [repository address] [server name] <options> <user id> <password>

Examples:

"mfds -x 1 c:\myrepository *"
"mfds -x 1 c:\myrepository * S"
"mfds -x 1 c:\myrepository * O"
"mfds /x 1 c:\myrepository * SO"
"mfds /x 1 c:\myrepository ESDEMO"
"mfds /x 1 c:\myrepository ESDEMO D myid mypwd"

Syntax for creating a readable journal file from a binary journal file:

mfds /t output-filename input-filename
Note:

If output-filename is not specified, a default file of journal.txt will be created in the same directory as the input-filename

If input-filename is not specified, the default journal.dat file as specified by the default MFDS options file (mfdsacfg.dat) will be used.

This option can only convert journal.dat files to text if they have originated on the same hardware and software platform; it is not guaranteed that journal files imported from UNIX can be read by Windows and visa versa.

Syntax for installing and uninstalling Windows services:

mfds /c
mfds /u
mfds /i

Parameters:

/d
Show debug information; this is a record of activity on the Directory Server that can be useful when investigating problems
/dn network-address
Show debug information and bind to the specific network adapter at network-address, where network-address is four decimal numbers of up to three digits separated by full stops.
/e root DNuser partition DNgroup partition DNresource partition DNschema formatldif-filenamesec-path
Export Directory Server users and groups from the MF Directory Server repository to an LDIF file:
  • root-DN

    The application partition to which all of the exported entries will be assigned.

  • user-partition-DN

    The name of the container within the application partition to which the exprted users will be assigned.

  • group-partition-DN

    The container within the application partition to which the exported groups will be assigned.

  • root-DN

    The container within the application partition to which the exported resource definitions will be assigned.

  • schema-format

    Values: 1 = Active Directory (Default).

  • sec-path

    The location of the MF Directory Server repository.

/j directory-path
Override the journal path. Journal data will be written to the filesystem directory that you specify. For example: mfds /j e:\journal
/l [schema partition Distinguished Name] optionldif-filename [schema-version-1] [schema-version-2]
Export the schema extensions that an LDAP server will require to support Micro Focus applications.
  • schema partition Distinguished Name

    Specifies the DN of the partition in the Directory Information Tree where the schema definition is held. The schema partition holds, amongst other things, attributeSchema and classSchema objectclass instances.

  • option

    Specifies the target directory server type: 0 = Microsoft Active Directory Application Mode (ADAM), 1 = Active Directory (Default), 2 = OpenLDAP, 3 = Sun Directory

    Note:

    If you specify the ldif-filename , you must also specify a value for this parameter.

  • ldif-filename

    Specifies the name of the destination file.

    Default: mfds_schema_[ mfds version ].ldf (e.g. mfds_schema_1.05.09.ldf)

  • schema-version-1

    Specifies the version of the schema extensions to be generated: 0 = current schema version (Default). Numbers greater than 0 specify older schema versions.

  • schema-version-2

    This option is used for upgrading from a previous schema. If schema-version-2 is specified and is less the schema-version-1, the output file is a delta between the schema-version-1 and schema-version-2.

    If schema-version-2 is greater than or equal to schema-version-1, this option is ignored.

/m
Display the location of the Directory Server repository.
/n network-address
Bind to the specific network adapter at network-address, where network-address is four decimal numbers of up to three digits separated by full stops.
/p port-number
Bind to a non-standard port.
Note:

Many programs depend on Directory Server using the default port (86). Therefore, if you use an alternative port, you may experience interoperability problems.

You should also consider carefully before using this option to run more than one Directory Server on the same machine. By default, both would use the same options file and repository, and might therefore encounter conflicts.

/r
Refuse access to the Enterprise Server Administration interface.
/s option [usernamepassword]
Request a controlled shutdown of a Directory Server and optionally the associated enterprise servers. If the Directory Server is not using the default port, the /p option must be used to specify the port that is being used.
Option:
  • Value 1: Shutdown the Directory Server only
  • Value 2: Shutdown the Directory Server and any associated enterprise servers.

Username and password: These must be supplied if the Directory Server is running with Restrict administration access checked.

/v
Show version information for Directory Server
/x [repository type]
1 = file:///
[server name]
* = export all servers
<opts>
  • D = (default) do not delete or overwrite any existing repository contents at specified location.
  • O = delete and overwrite any existing repository contents at specified location.
  • S = export server and security manager configuration.
<user id> <password>
These are the MFDS credentials required if administration access is restricted.

Comments:

The command to start the Directory Server can be inserted into your startup shell script; then the Directory Server will be started automatically when the machine is started. The mfds command must be inserted after the command to start up TCP/IP, because Directory Server needs TCP/IP to be running. If the command has been added to your startup shell script you would normally need to start the Directory Server only if you performed a shutdown since you started the machine.

Note: Issuing an mfds command with any of the parameters /e, /l, /m, /v does not start the Directory Server.

On UNIX you should use a dash (-) before a parameter as an alternative to a forward slash (/).

Parent topic: Administration and Configuration Commands


mfpackage

This utility is used for maintaining services and packages installed on an enterprise server. Its function is to delete all services and packages in a given namespace for a given enterprise server region, and is equivalent to deleting the services and packages using the Micro Focus Administration Console (MFDS). It can also be used to prepare the server before deploying a new version of the service..
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

mfpackage [options] command service-namespace [parameters]

Parameters:

command | undeploy. Deletes the services and packages in the supplied namespace.
options | -m URL | host | Directory. Supported URL schemes are "file", "mrpi", and "ldap". Default is MFDS on the local system using the default port (equivalent to mrpi://localhost:86).
 | -s server | Operates on packages and services for this server. Required for undeploy.
 | -p password | Optional password for binding to directory.
 | service- namespace | The namespace for the services and packages. For a web service, this is everything before the "#" character in the service/package name. For a J2EE service, it is everything before the final "." character.

Example:

mfpackage -m mrpi://localhost -s ESDEMO undeploy http://tempuri.org/wmapserv
Parent topic: Administration and Configuration Commands


Error Messages

  • Client Messages
  • Directory Server Error Messages
  • Enterprise Server Error Messages
Parent topic: Enterprise Server Reference


Client Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic lists the messages that clients of Enterprise Server can display.

Error number | Meaning
-1 | Error status is unknown
0 | Success
00001 | Internal error in common client
00002 | Feature has not been implemented
00003 | Unsupported protocol version or feature
00004 | Requested object not found (in Directory Server repository)
00005 | Not used
00006 | Error in parameters to function
00007 | Resource unavailable, for example, memory allocation failed
00008 | Communications error
00009 | Object is in wrong state for operation
00010 | Bad data problem (for example, non-HTTP response to HTTP request)
00011 | Operating system error
00012 | An external component failed (for example MLDAP unable to bind to Directory Server)
00013 | Data was truncated
00014 | No data was available, possibly because the server was not available
00015 | Client request timed out
00016 | Requested service is not available
00017 | No user data was returned by the server
00100 | Invalid IDT version
00101 | Invalid message type
00102 | Servicename not found in IDT
00103 | Unsupported mapping
00150 | Unable to initialise request handler
00151 | Unable to initialise interface mapper
00250 | Unable to initialise SOAP parser
00400 | Invalid binary protocol version
00401 | Unrecognised binary protocol message
00402 | Program/entry point not found
00450 | Invalid namespace for SOAP envelope
00451 | Invalid namespace for SOAP header
00452 | Invalid namespace for SOAP body
00453 | Invalid SOAP message
00454 | No SOAP URI in SOAP message
00455 | SOAP action URI differs from SOAP Body URI
00456 | Unable to resolve href in SOAP message
00457 | Unrecognised encoding style
00458 | Illegal character in SOAP string
00500 | Parameter not found in IDT
00501 | External data not located
00502 | Invalid implementation language
00503 | Unsupported mapping
00504 | Expected mapping not defined
00505 | Invalid ODO item
00506 | Invalid structured mapping
00507 | Insuffient subscripts for external item
00508 | Subscript for external item does not exist
00509 | Too many subscripts for external item
00510 | Error in exit handler
00600 | External field not found
00601 | Unsupported external data type
00602 | Expected parameter not supplied by external interface
00603 | Expected external structure field not found
00604 | Expected external array field not found
00605 | Incorrect number of parameters supplied
00606 | Incorrect number of fields in supplied structure
00607 | External data type mismatch
00608 | Unknown external data type
00609 | Incorrect number of array elements
00610 | Too many array elements passed in message
01400 | HTTP response: bad request
01401 | HTTP response: unauthorized
01403 | HTTP response: forbidden
01404 | HTTP response: not found
01405 | HTTP response: method not allowed
01406 | HTTP response: not acceptable
01407 | HTTP response: proxy authentication required
01408 | HTTP response: request timeout
01409 | HTTP response: conflict
01410 | HTTP response: gone
01411 | HTTP response: length required
01412 | HTTP response: precondition failed
01413 | HTTP response: request entity too large
01414 | HTTP response: request-URI too long
01415 | HTTP response: unsupported media type
01416 | HTTP response: requested range not satisfiable
01417 | HTTP response: expectation failed
01500 | HTTP response: internal server error
01501 | HTTP response: not implemented
01502 | HTTP response: bad gateway
01503 | HTTP response: service unavailable
01504 | HTTP response: gateway timeout
01505 | HTTP version not supported
02000 | SOAP response fault
Parent topic: Error Messages


Directory Server Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic lists the messages that the Directory Server can display, and gives an explanation or advice or both for those that are not self-explanatory.

Format of Messages

The Directory Server displays messages in the status line in the format:

MDSnnnns message-text

where MDS stands for Micro Focus Directory Server and the variables are:

nnnn | A four-digit message number
s | One of the following severity codes: I Information only; no action is required W Warning: the action you attempted succeeded but with results that you need to be aware of E Error: the action you attempted failed
message-text | The text of the message

Messages with the severity E (for Error) appear in red.

  • Directory Server Error Messages 0 to 20
    Lists the Directory Server error messages from 0 through to 20
  • Directory Server Error Messages 21 to 40
    Lists the Directory Server Error Messages 21 to 40
  • Directory Server Error Messages 41 to 60
    Lists the Directory Server Error Messages, 41 to 60
  • Directory Server Error Messages 61 to 80
    Lists the Directory Server Error Messages 61 to 80
  • Directory Server Error Messages 81 to end
    Lists the Directory Server Error Messages 81 to the last error message in the range.
Parent topic: Error Messages


Directory Server Error Messages 0 to 20

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0000I OK
    The Directory Server has executed your previous instruction successfully
  • MDS0001I Logged on OK
    You have successfully logged on.
  • MDS0002E Logon failed
    Either the user ID or password used to log on were incorrect.
  • MDS0003I Logged off OK
    You have successfully logged off.
  • MDS0004I Repository cleared OK
    All the information in the current repository has been deleted successfully.
  • MDS0005I Network search complete
    The Directory Server has finished searching the network for other instances of Directory Server.
  • MDS0006I All objects copied successfully
  • MDS0007E Duplicate server exists
    You tried to create a server with the same name as one that already exists.
  • MDS0008E Duplicate server name already exists
    You tried to create a server with the same name as one that already exists.
  • MDS0009E Invalid server specified.
    You have specified an invalid server name or IP address when copying an enterprise server.
  • MDS0010E Invalid endpoint specified
    The address or port value or syntax of the endpoint value are incorrect or could not be understood by the Directory Server.
  • MDS0012E Duplicate service name exists
    You tried to create a service with the same name as one that already exists for this enterprise server.
  • MDS0013E Duplicate listener exists
    You tried to create a listener with the same name as one that already exists for this enterprise server.
  • MDS0014E Duplicate user already exists
    You tried to add a user but specified a user ID that already exists.
  • MDS0015E Schema Administrators cannot reduce their own permission level
    If you have logged on as a Schema Administrator, you cannot reduce your own permission level. This is because if you did so, it would be impossible for any users to be added, updated or deleted.
  • MDS0016E Invalid endpoint specified
    You specified an invalid endpoint for a listener.
  • MDS0017E Object must have a name
    You tried to add an object (such as a service or listener) but did not give it a name.
  • MDS0018I New server session
    The Directory Server has been stopped and restarted since the last time the browser connected to it.
  • MDS0019I Client session has timed out: please log on again
    A client session expires when the client performs no action for a period that exceeds the timeout period. When this occurs the client is automatically logged out and must log on again to continue working.
  • MDS0020E Minimum client timeout is 60 seconds
    You entered an invalid client timeout period.
Parent topic: Directory Server Error Messages


MDS0000I OK

Parent topic: Directory Server Error Messages 0 to 20


MDS0001I Logged on OK

Parent topic: Directory Server Error Messages 0 to 20


MDS0002E Logon failed

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Retype your user ID and password, ensuring that you enter them correctly. User IDs and passwords are case sensitive.

Parent topic: Directory Server Error Messages 0 to 20


MDS0003I Logged off OK

Parent topic: Directory Server Error Messages 0 to 20


MDS0004I Repository cleared OK

Parent topic: Directory Server Error Messages 0 to 20


MDS0005I Network search complete

Parent topic: Directory Server Error Messages 0 to 20


MDS0006I All objects copied successfully

Parent topic: Directory Server Error Messages 0 to 20


MDS0007E Duplicate server exists

Parent topic: Directory Server Error Messages 0 to 20


MDS0008E Duplicate server name already exists

Parent topic: Directory Server Error Messages 0 to 20


MDS0009E Invalid server specified.

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Repeat the operation specifying a valid server name of up to 8 characters with no include angle brackets (<>) or ampersands (&).

Parent topic: Directory Server Error Messages 0 to 20


MDS0010E Invalid endpoint specified

Parent topic: Directory Server Error Messages 0 to 20


MDS0012E Duplicate service name exists

Parent topic: Directory Server Error Messages 0 to 20


MDS0013E Duplicate listener exists

Parent topic: Directory Server Error Messages 0 to 20


MDS0014E Duplicate user already exists

Parent topic: Directory Server Error Messages 0 to 20


MDS0015E Schema Administrators cannot reduce their own permission level

Parent topic: Directory Server Error Messages 0 to 20


MDS0016E Invalid endpoint specified

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Specify an endpoint of the form:

protocol:ip-address:port

where:

  • protocol is tcp
  • ip-address is either the text host name or IP address of the listener. An asterisk (*) indicates that the address is dynamically assigned for the listener when it starts.
  • port is the port value. An asterisk (*) indicates that the port is dynamically assigned for the listener when it starts
Parent topic: Directory Server Error Messages 0 to 20


MDS0017E Object must have a name

Parent topic: Directory Server Error Messages 0 to 20


MDS0018I New server session

Parent topic: Directory Server Error Messages 0 to 20


MDS0019I Client session has timed out: please log on again

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

You can change the client timeout period on the Configure Options page.

Parent topic: Directory Server Error Messages 0 to 20


MDS0020E Minimum client timeout is 60 seconds

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Enter a value of 60 or greater, or 01, which indicates an indefinite timeout period.

Parent topic: Directory Server Error Messages 0 to 20


Directory Server Error Messages 21 to 40

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0021E Minimum page size is 5 entries
    You entered an invalid minimum page size for the journal.
  • MDS0022E Minimum journal size is 32 KB
    You entered an invalid minimum journal size for the journal.
  • MDS0023E Insufficient memory for this operation
    There was insufficient computer memory for this operation to succeed.
  • MDS0024E Password mismatch
    Password mismatch.
  • MDS0025E Confirmation password mismatch
    The confirmation password does not match the password you first entered.
  • MDS0026E Old password required
    Old password required.
  • MDS0027E New password required
    You have not specified a password when creating a new user.
  • MDS0028E Invalid characters in password
    Invalid characters in password.
  • MDS0029E Selected object does not exist
    You tried to edit an object that another user has just deleted.
  • MDS0030W Some or all objects not copied: see journal for details
    You tried to copy a server but the Directory Server was unable to copy all objects related to the server.
  • MDS0031E Maximum port value is 65535
    You entered a port value in an endpoint that exceeds 65535.
  • MDS0032E Object could not be added
    There was an error adding the object. See journal for more details of the error.
  • MDS0035E Minimum object limit is 64
    You tried to reduce the limit for the maximum number of objects below 64, which is not allowed.
  • MDS0036E Maximum object limit is 9999
    You tried to reduce the limit for the maximum number of objects above 9999, which is not allowed.
  • MDS0037E Operation would breach the configured object limit
    This action has been rejected because to perform it would mean increasing the number of objects in the repository above the maximum object count.
  • MDS0038E Minimum object limit is smaller than the current number of objects
    You tried to reduce the maximum object count to less than the current number of registered objects.
Parent topic: Directory Server Error Messages


MDS0021E Minimum page size is 5 entries

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Enter a value of 5 or greater.

Parent topic: Directory Server Error Messages 21 to 40


MDS0022E Minimum journal size is 32 KB

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Enter a value of 32 (KB) or greater.

Parent topic: Directory Server Error Messages 21 to 40


MDS0023E Insufficient memory for this operation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Try closing some application programs.

Parent topic: Directory Server Error Messages 21 to 40


MDS0024E Password mismatch

Parent topic: Directory Server Error Messages 21 to 40


MDS0025E Confirmation password mismatch

Parent topic: Directory Server Error Messages 21 to 40


MDS0026E Old password required

Parent topic: Directory Server Error Messages 21 to 40


MDS0027E New password required

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Specify a valid password. Passwords can contain alphabetical and numeric characters only and are case sensitive.

Parent topic: Directory Server Error Messages 21 to 40


MDS0028E Invalid characters in password

Parent topic: Directory Server Error Messages 21 to 40


MDS0029E Selected object does not exist

Parent topic: Directory Server Error Messages 21 to 40


MDS0030W Some or all objects not copied: see journal for details

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

View the journal to find out which objects were not copied. Add them to the server individually.

Parent topic: Directory Server Error Messages 21 to 40


MDS0031E Maximum port value is 65535

Parent topic: Directory Server Error Messages 21 to 40


MDS0032E Object could not be added

Parent topic: Directory Server Error Messages 21 to 40


MDS0035E Minimum object limit is 64

Parent topic: Directory Server Error Messages 21 to 40


MDS0036E Maximum object limit is 9999

Parent topic: Directory Server Error Messages 21 to 40


MDS0037E Operation would breach the configured object limit

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

You can change the maximum object count on the Configure Options page.

Parent topic: Directory Server Error Messages 21 to 40


MDS0038E Minimum object limit is smaller than the current number of objects

Parent topic: Directory Server Error Messages 21 to 40


Directory Server Error Messages 41 to 60

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0043I Journal exported as text into file journal.txt OK
    The journal file has been successfully converted to a text file called journal.txt, located in the $COBDIR\bin directory.
  • MDS0044E Server name missing
    You tried to add a server without the mandatory server name value.
  • MDS0045E Duplicate request handler or package name exists
    You tried to create a request handler or a package with the same name as one that already exists for this enterprise server.
  • MDS0047E Package must have an IDT path
    You tried to add a package without a mandatory IDT path value, or you deleted the IDT path value while editing the package.
  • MDS0048E Server refused state change request
    The change you requested requires the enterprise server to take immediate action, but the Directory Server did not receive confirmation from the enterprise server that the action was completed.
  • MDS0049E Server refused state change request reason code:
    The change you requested requires the enterprise server to take immediate action, but the Directory Server did not receive confirmation from the enterprise server that the action was completed. The internal reason code is shown.
  • MDS0050E Server instance count must be at least 1
    You tried to reduce the number of service execution processes to less than 1.
  • MDS0051I Value change request accepted
    A request to change the number of service execution processes or licenses has been accepted.
  • MDS0052I Diagnostic dump request accepted
    The enterprise server has accepted the request to create a dump.
  • MDS0053E Diagnostic dump request failed
    The enterprise server has rejected the request to create a dump.
  • MDS0054I Configuration saved
    The current Directory Server configuration options have been saved.
  • MDS0055I Configuration defaults restored
    The default Directory Server configuration options have been restored.
  • MDS0056E Insufficient permission level for request
    You tried to perform an action that your permission level does not allow.
  • MDS0057E Resource manager ID field must have a value
    You tried to add an external resource manager in the enterprise server definition without a mandatory ID value or you deleted the ID value while editing the resource manager definition.
  • MDS0058E Resource manager name field must have a value
    You tried to add an external resource manager in the enterprise server definition without a mandatory name value or you deleted the name value while editing the resource manager definition.
  • MDS0059E Resource manager module field must have a value
    You tried to add an external resource manager in the enterprise server definition without a mandatory module value or you deleted the module value while editing the resource manager definition.
  • MDS0060E MFRHBINP cannot be deleted
    You tried to delete the MFRHBINP request handler. This request handler is required for some of the enterprise server internal functions, so it cannot be deleted.
Parent topic: Directory Server Error Messages


MDS0043I Journal exported as text into file journal.txt OK

Parent topic: Directory Server Error Messages 41 to 60


MDS0044E Server name missing

Parent topic: Directory Server Error Messages 41 to 60


MDS0045E Duplicate request handler or package name exists

Parent topic: Directory Server Error Messages 41 to 60


MDS0047E Package must have an IDT path

Parent topic: Directory Server Error Messages 41 to 60


MDS0048E Server refused state change request

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Refresh the Enterprise Server Administration display to see if the action has now completed. Check the enterprise server console log and communications console log to see if any additional information is available. If the action you requested is temporary, such as changing a listener's status, you might want to try again. Otherwise, your change will take effect the next time you start the enterprise server.

Parent topic: Directory Server Error Messages 41 to 60


MDS0049E Server refused state change request reason code:

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Refresh the Enterprise Server Administration display to see if the action has now completed. Check the enterprise server console log and communications console log to see if any additional information is available. If the action you requested is temporary, such as changing a listener's status, you might want to try again. Otherwise, your change will take effect the next time you start the enterprise server.

Parent topic: Directory Server Error Messages 41 to 60


MDS0050E Server instance count must be at least 1

Parent topic: Directory Server Error Messages 41 to 60


MDS0051I Value change request accepted

Parent topic: Directory Server Error Messages 41 to 60


MDS0052I Diagnostic dump request accepted

Parent topic: Directory Server Error Messages 41 to 60


MDS0053E Diagnostic dump request failed

Parent topic: Directory Server Error Messages 41 to 60


MDS0054I Configuration saved

Parent topic: Directory Server Error Messages 41 to 60


MDS0055I Configuration defaults restored

Parent topic: Directory Server Error Messages 41 to 60


MDS0056E Insufficient permission level for request

Parent topic: Directory Server Error Messages 41 to 60


MDS0057E Resource manager ID field must have a value

Parent topic: Directory Server Error Messages 41 to 60


MDS0058E Resource manager name field must have a value

Parent topic: Directory Server Error Messages 41 to 60


MDS0059E Resource manager module field must have a value

Parent topic: Directory Server Error Messages 41 to 60


MDS0060E MFRHBINP cannot be deleted

Parent topic: Directory Server Error Messages 41 to 60


Directory Server Error Messages 61 to 80

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0061I Stopping and deleting all servers...
    You made a "Delete All" request and asked for servers to be stopped before they are deleted. This status is shown while the servers are in "Stopping" state.
  • MDS0062E Entry range invalid
    You asked to view an enterprise server console entry outside the range of existing entries.
  • MDS0063E Cannot delete a listener which is associated with a service
    You tried to delete a listener which is associated with a service.
  • MDS0064E Cannot delete a package which is associated with a service
    You tried to delete a package which is associated with a service.
  • MDS0065E Requested new listener status not possible when server is stopped
    You tried to make a change to the status of a listener that is not possible when the enterprise server is not started.
  • MDS0066E There are no servers to delete
    You tried to perform a "Delete All" when no server information is stored in the current repository.
  • MDS0067E less than greater than ampersand characters are not allowed in object names
    You tried to add an object using a name containing one or more of the characters < > and &, which are not allowed.
  • MDS0068I Schema updated
    You have successfully updated the schema.
  • MDS0069I All servers deleted
    You have deleted the Directory Server schema.
  • MDS0070I Data imported
    You have imported a repository into the Directory Server schema.
  • MDS0071E Data import failed
    You have attempted to import a repository into the Directory Server schema, but the import failed.
  • MDS0072I Server data saved
    You have successfully saved the data for the current server.
  • MDS0073E Server data save failed
    You have attempted to save the data for one server, but the save failed.
  • MDS0074E User name required
    You tried to add a new user without supplying a user ID.
  • MDS0075E Too many multi-byte characters in name
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0076E Too many multi-byte characters in path
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0077E Too many multi-byte characters in type
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0078E Too many multi-byte characters in ID
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0079E Too many multi-byte characters in module
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
  • MDS0080E Too many multi-byte characters in string
    You entered one or more multi-byte characters into a fixed-length field, which resulted in the limit for the number of bytes being exceeded. In Japanese and some other languages a typed character can have more than one byte associated with it: so although the entry field will allow you to type the characters in, the number of bytes exceeds the field limit.
Parent topic: Directory Server Error Messages


MDS0061I Stopping and deleting all servers...

Parent topic: Directory Server Error Messages 61 to 80


MDS0062E Entry range invalid

Parent topic: Directory Server Error Messages 61 to 80


MDS0063E Cannot delete a listener which is associated with a service

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Disassociate the listener from the services with which it is associated, or delete the services that reference it. Then delete it.

Parent topic: Directory Server Error Messages 61 to 80


MDS0064E Cannot delete a package which is associated with a service

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Disassociate the package from the services with which it is associated, or delete the services that reference it. Then delete it.

Parent topic: Directory Server Error Messages 61 to 80


MDS0065E Requested new listener status not possible when server is stopped

Parent topic: Directory Server Error Messages 61 to 80


MDS0066E There are no servers to delete

Parent topic: Directory Server Error Messages 61 to 80


MDS0067E less than greater than ampersand characters are not allowed in object names

Parent topic: Directory Server Error Messages 61 to 80


MDS0068I Schema updated

Parent topic: Directory Server Error Messages 61 to 80


MDS0069I All servers deleted

Parent topic: Directory Server Error Messages 61 to 80


MDS0070I Data imported

Parent topic: Directory Server Error Messages 61 to 80


MDS0071E Data import failed

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

See the journal for more detailed diagnostics.

Parent topic: Directory Server Error Messages 61 to 80


MDS0072I Server data saved

Parent topic: Directory Server Error Messages 61 to 80


MDS0073E Server data save failed

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

See the journal for more detailed diagnostics.

Parent topic: Directory Server Error Messages 61 to 80


MDS0074E User name required

Parent topic: Directory Server Error Messages 61 to 80


MDS0075E Too many multi-byte characters in name

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0076E Too many multi-byte characters in path

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0077E Too many multi-byte characters in type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0078E Too many multi-byte characters in ID

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0079E Too many multi-byte characters in module

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


MDS0080E Too many multi-byte characters in string

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Reduce the number of characters entered until the entry is accepted.

Parent topic: Directory Server Error Messages 61 to 80


Directory Server Error Messages 81 to end

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • MDS0081W A duplicate port value has been used: this may cause server startup errors
    You specified a port number for a listener or a server that is already in use. If both are started at the same time then this will cause startup problems. Depending on the operating system and the TCP stack implementation the second one to start might take the port or may refuse to start up, or some other problem might occur, which might or might not be reported to you.
  • MDS0082E Requested license value invalid, minimum value is 0
    You have asked for a negative number of licenses when creating an enterprise server. The enterprise server will be created with no licenses.
  • MDS0083W Cannot set auto-refresh period if web browser timeout is set
    You tried to set an auto-refresh period when a Web browser timeout period is set on the Configure Options page. This is not allowed if user access on that page is also set to restricted, because each refresh restarts the timeout countdown.
  • MDS0084E Cannot restore from current repository path
    You have tried to restore the repository from the location of the current repository.
  • MDS0085W Value changed but not saved
    You have changed a value on one of the Edit Server tabs, then switched to another tab or page without saving your changes.
  • MDS0086I At least one Communications Process must auto-start
    You have attempted to turn off auto-start for all the communications processes that belong to an enterprise server. At least one must auto-start. The change is ignored.
  • MDS0087E MFRHBINP cannot be renamed
    You have attempted to rename the Micro Focus request handler MFRHBINP. This is not permitted because if it were possible to rename it, it could then be deleted. Enterprise Server will not work without the presence of this request handler.
  • MDS0091E ISC listener port must have a valid value
    MDS0091E ISC listener port has an invalid value,
  • MDS0095E Duplicate group name exists
    The group name exists. A user group name must be unique.
  • MDS0096I Server configuration updated
    This message is displayed after an administrator has run the Validate operation on a configuration, and then applied any suggested updates.
  • MDS0097E Duplicate initiator name exists
    An initiator name must be unique within the enterprise server configuration.
  • MDS0098W Cannot over-write existing repository data
    There is existing repository data in the chosen directory. Choose a different directory.
  • MDS0099I Server already in requested state
    Displayed whe a request is made to start an already-started enterprise server.
  • MDS0100E Duplicate printer name exists
    A printer name must be unique within the server configuration.
  • MDS0101E The maximum number of Communications Processes per server is 32
    When copying Communications Processes in the listener list page, the maximum number allowed is 32.
  • MDS0102W Passwords must contain alphanumeric characters only
    The password field for internal and external security users accepts only alphanumeric characters.
  • MDS0103E Security Manager already referenced in list
    When specifying a priority list of Security Managers, each entry in the list must refer to a unique Security Manager (no duplicate entries allowed).
  • MDS0104E There must be at least one Security Manager in list
    There must be at least one Security Manager in the Security Manager list.
  • MDS0105E Both certificate and keyfile required
    If both the MFDS SSL option and custom certificate option have both been specified, then a certificate and keyfile have to be specified.
  • MDS0106E Duplicate Security Manager name exists
    A Security Manager name must be unique within MFDS.
  • MDS0107E Security Managers cannot use a reserved module name
    Some Security Manager names are reserved for internal use only, for example “mfds_esm”.
  • MDS0108E Users must be a member of #AllUsrs group
    If using MFDS Internal Security, all users must be a member of the “#AllUsrs” group and cannot be removed from it.
  • MDS0109E Cannot copy deployed services or packages if server working mode is changed
    If copying an ES server definition to change the working mode from 32-bit to 64-bit or 64-bit to 32-bit, the deployed services of the original server will not be compatible with the new working mode. Therefore, the server definition cannot be copied.
  • MDS0110W The specified configuration change may not take effect until the server is restarted
    When changing the state of a service when an ES server is started, the requested state may not come into effect until the server is restarted.
  • MDS0111W Update request failure message CASRD1006E detected in the ES console log
    There has been a problem updating the started ES server with the requested configuration change.
  • MDS0112I Update success message CASRD1001I detected for this object in the ES console log
    The requested configuration change has been accepted by the started ES instance.
  • MDS0113W Users who are members of the #System user group cannot log on interactively
    When using MFDS Internal Security, the system accounts defined in the “#System” group, used internally by default in ES, cannot be used to log into the Enterprise Server Administration GUI if user access is set to restricted.
  • MDS1003E LDAP server connection error
    You have attempted to change the location of the MFDS repository to an LDAP directory server, and there is an error connecting to the server specified. The LDAP server error code and details are included in the message. Refer to your LDAP provider documentation for more information on the error.
Parent topic: Directory Server Error Messages


MDS0081W A duplicate port value has been used: this may cause server startup errors

Parent topic: Directory Server Error Messages 81 to end


MDS0082E Requested license value invalid, minimum value is 0

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Update the number of licenses on the Edit Server > Properties > General page.

Parent topic: Directory Server Error Messages 81 to end


MDS0083W Cannot set auto-refresh period if web browser timeout is set

Parent topic: Directory Server Error Messages 81 to end


MDS0084E Cannot restore from current repository path

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

Specify a valid backup location from which to restore the repository.

Parent topic: Directory Server Error Messages 81 to end


MDS0085W Value changed but not saved

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Resolution:

If you intended to make the change, return to the tab on which you made the change, make it again and click OK.

Parent topic: Directory Server Error Messages 81 to end


MDS0086I At least one Communications Process must auto-start

Parent topic: Directory Server Error Messages 81 to end


MDS0087E MFRHBINP cannot be renamed

Parent topic: Directory Server Error Messages 81 to end


MDS0091E ISC listener port must have a valid value

Parent topic: Directory Server Error Messages 81 to end


MDS0095E Duplicate group name exists

Parent topic: Directory Server Error Messages 81 to end


MDS0096I Server configuration updated

Parent topic: Directory Server Error Messages 81 to end


MDS0097E Duplicate initiator name exists

Parent topic: Directory Server Error Messages 81 to end


MDS0098W Cannot over-write existing repository data

Parent topic: Directory Server Error Messages 81 to end


MDS0099I Server already in requested state

Parent topic: Directory Server Error Messages 81 to end


MDS0100E Duplicate printer name exists

Parent topic: Directory Server Error Messages 81 to end


MDS0101E The maximum number of Communications Processes per server is 32

Parent topic: Directory Server Error Messages 81 to end


MDS0102W Passwords must contain alphanumeric characters only

Parent topic: Directory Server Error Messages 81 to end


MDS0103E Security Manager already referenced in list

Parent topic: Directory Server Error Messages 81 to end


MDS0104E There must be at least one Security Manager in list

Parent topic: Directory Server Error Messages 81 to end


MDS0105E Both certificate and keyfile required

Parent topic: Directory Server Error Messages 81 to end


MDS0106E Duplicate Security Manager name exists

Parent topic: Directory Server Error Messages 81 to end


MDS0107E Security Managers cannot use a reserved module name

Parent topic: Directory Server Error Messages 81 to end


MDS0108E Users must be a member of #AllUsrs group

Parent topic: Directory Server Error Messages 81 to end


MDS0109E Cannot copy deployed services or packages if server working mode is changed

Parent topic: Directory Server Error Messages 81 to end


MDS0110W The specified configuration change may not take effect until the server is restarted

Parent topic: Directory Server Error Messages 81 to end


MDS0111W Update request failure message CASRD1006E detected in the ES console log

Parent topic: Directory Server Error Messages 81 to end


MDS0112I Update success message CASRD1001I detected for this object in the ES console log

Parent topic: Directory Server Error Messages 81 to end


MDS0113W Users who are members of the #System user group cannot log on interactively

Parent topic: Directory Server Error Messages 81 to end


MDS1003E LDAP server connection error

Parent topic: Directory Server Error Messages 81 to end


Enterprise Server Error Messages

  • CASCD Error Messages
    Console Daemon error messages.
  • CASCF Error Messages
    Configuration support error messages.
  • CASCL Error Messages
    Client management error messages
  • CASDB Error Messages
    IMS database control error messages.
  • CASDU Error Messages
    Dump Control error messages
  • CASFC Error Messages
    File Control error messages
  • CASFD Error Messages
    Dump Formatter error messages
  • CASFF Error Messages
    File Finder error messages
  • CASRM Error Messages
    Resource Manager Control error messages
  • CASSP Error Messages
    Syncpoint and Recovery Services error messages.
  • CASST Error Messages
    Server termination error messages.
  • CASXO Error Messages
    Transaction Manager error messages.
Parent topic: Error Messages


CASCD Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD0001 - CASCD0015
  • CASCD0016 - CASCD0031
  • CASCD0050 - CASCD0099
  • CASCD0100 - CASCD0117
  • CASCD0120 - CASCD0139
  • CASCD0141 - CASCD0159
  • CASCD0160 - CASCD0175
  • CASCD1001 - CASCD1056
  • CASCD1057 - CASCD1069
  • CASCD1070 - CASCD1200
  • CASCD4002 - CASCD4007
Parent topic: Enterprise Server Error Messages


CASCD0001 - CASCD0015

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD0001F
    The request to start a CAS daemon was not successful
  • CASCD0002S
    CAS failed to create a new process in which to run the CAS daemon A UNIX 'fork' call returned with errno set to errno
  • CASCD0003S
    CAS was unable to run the COBOL RTS in the CAS daemon process A UNIX 'exec' call returned with errno set to errno
  • CASCD0004S
    CAS failed to create named pipe 'pipe-name' which was to be used for communication with the CAS daemon. A UNIX 'mknod' call returned with errno set to errno
  • CASCD0005S
    CAS failed to open named pipe 'pipe-name' which was to be used to receive messages from the CAS daemon A UNIX 'fopen' call returned with errno set to errno
  • CASCD0006S
    An error occurred attempting to read from the named pipe pipe-namewhich was being used to receive messages from the CAS daemon A UNIX 'fgets' call returned with errno set to errno
  • CASCD0007S
    The CAS daemon process has terminated without first sending a severe or fatal error message process status is the status as returned by the UNIX 'wait' call
  • CASCD0008F
    CAS failed to create a UNIX message queue A UNIX message queue call returned with errno set to functionThe call that failed is specified by function, where: 1 = msgget 2 = msgctl 3 = msgrcv 4 = msgsnd
  • CASCD0009F
    CAS detected an error whilst reading from a UNIX message queue A UNIX message queue call returned with errno set to functionThe call that failed is specified by function, where: 1 = msgget 2 = msgctl 3 = msgrcv 4 = msgsnd
  • CASCD0010F
    CAS failed to delete a UNIX message queue during shutdown A UNIX message queue call returned with errno set to functionThe call that failed is specified by function, where: 1 = msgget 2 = msgctl 3 = msgrcv 4 = msgsnd
  • CASCD0011F
    CAS failed to open the system console log file The COBOL file status after failure is RC1,RC2
  • CASCD0012F
    CAS failed to write to the system console log file because the system disk is full.
  • CASCD0013F
    Only one CAS Daemon is required, attempts to start more are rejected
  • CASCD0014F
    A UNIX setuid call has failed, returning errno set to errno. This is probably caused by an attempt to start an CAS Daemon without super-user authority
  • CASCD0015W
    After the CAS Daemon has been created an attempt is made to communicate with it. This attempt was unsuccessful. It is possible that the console daemon may start successfully and this error occurred due to a slow machine.
Parent topic: CASCD Error Messages


CASCD0001F

The request to start a CAS daemon was not successful
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS daemon is not started
Resolution:
Check previous messages for cause of error, correct the problem and retry if appropriate
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0001 - CASCD0015


CASCD0002S

CAS failed to create a new process in which to run the CAS daemon A UNIX 'fork' call returned with errno set to errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS daemon is not started
Resolution:
Correct the cause of the error and retry
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0001 - CASCD0015


CASCD0003S

CAS was unable to run the COBOL RTS in the CAS daemon process A UNIX 'exec' call returned with errno set to errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS daemon is not started
Resolution:
Correct the cause of the error and retry
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0001 - CASCD0015


CASCD0004S

CAS failed to create named pipe 'pipe-name' which was to be used for communication with the CAS daemon. A UNIX 'mknod' call returned with errno set to errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS daemon is not started
Resolution:
Correct the cause of the error and retry
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0001 - CASCD0015


CASCD0005S

CAS failed to open named pipe 'pipe-name' which was to be used to receive messages from the CAS daemon A UNIX 'fopen' call returned with errno set to errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS daemon is not started
Resolution:
Correct the cause of the error and retry
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0001 - CASCD0015


CASCD0006S

An error occurred attempting to read from the named pipe pipe-namewhich was being used to receive messages from the CAS daemon A UNIX 'fgets' call returned with errno set to errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS daemon is not started
Resolution:
Correct the cause of the error and retry
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0001 - CASCD0015


CASCD0007S

The CAS daemon process has terminated without first sending a severe or fatal error message process status is the status as returned by the UNIX 'wait' call
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS daemon is not started
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0001 - CASCD0015


CASCD0008F

CAS failed to create a UNIX message queue A UNIX message queue call returned with errno set to functionThe call that failed is specified by function, where: 1 = msgget 2 = msgctl 3 = msgrcv 4 = msgsnd
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS Daemon is not started
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
standard error
Module:
dfhmd
Parent topic: CASCD0001 - CASCD0015


CASCD0009F

CAS detected an error whilst reading from a UNIX message queue A UNIX message queue call returned with errno set to functionThe call that failed is specified by function, where: 1 = msgget 2 = msgctl 3 = msgrcv 4 = msgsnd
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS System shuts down
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0001 - CASCD0015


CASCD0010F

CAS failed to delete a UNIX message queue during shutdown A UNIX message queue call returned with errno set to functionThe call that failed is specified by function, where: 1 = msgget 2 = msgctl 3 = msgrcv 4 = msgsnd
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS Daemon continues shutdown
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0001 - CASCD0015


CASCD0011F

CAS failed to open the system console log file The COBOL file status after failure is RC1,RC2
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS Daemon is not started
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
standard error
Module:
dfhmd
Parent topic: CASCD0001 - CASCD0015


CASCD0012F

CAS failed to write to the system console log file because the system disk is full.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
All output on standard error and system log on UNIX
Resolution:
Free up space on the system disk
Destination:
standard error
Module:
dfhmd
Parent topic: CASCD0001 - CASCD0015


CASCD0013F

Only one CAS Daemon is required, attempts to start more are rejected
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Terminate existing Daemon if restart is required
Destination:
standard error
Module:
dfhmd
Parent topic: CASCD0001 - CASCD0015


CASCD0014F

A UNIX setuid call has failed, returning errno set to errno. This is probably caused by an attempt to start an CAS Daemon without super-user authority
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS Daemon is not started
Resolution:
Retry the request from a super-user
Destination:
standard error
Module:
dfhmd
Parent topic: CASCD0001 - CASCD0015


CASCD0015W

After the CAS Daemon has been created an attempt is made to communicate with it. This attempt was unsuccessful. It is possible that the console daemon may start successfully and this error occurred due to a slow machine.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
If the console daemon starts the system can continue as normal. If the console daemon does not start then no regions can be started.
Resolution:
Wait to see if the console daemon initializes, if it does not then check if any error messages were displayed or written to the console.log file.
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0001 - CASCD0015


CASCD0016 - CASCD0031

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD0016W
    The region name specified on the command line to dfhtxs to auto-start was found to be invalid. If the region can not be located under $CASDIR or appropriate REGIONBASE directory then it is removed from the auto-start region list.
  • CASCD0022E
    There is no CAS Daemon to shutdown.
  • CASCD0023S
    The specified option is not valid
  • CASCD0024S
    Too many arguments were specified, the maximum permitted is 1.
  • CASCD0025S
    A UNIX call returned with errno set to errnoThe call that failed is specified by errno, where: 1 = msgget 2 = msgsnd 3 = fgets 4 = fopen 5 = mknod
  • CASCD0026S
    The CAS Daemon did not respond to the shutdown request, it is not possible to determine the current state of the daemon
  • CASCD0027W
    The immediate shutdown option of the console daemon shutdown utility abends all running regions. Data may be lost or the system may be left in an unstable state. This option should only be used as a last resort. It is recommended that each region is shutdown cleanly before using the dfhtxp command.
  • CASCD0028I
    If the CAS Console Daemon is not running with the effective user ID of root (UID=0) this message details the current effective user id. The effective user ID that the CAS console Daemon runs as, and all region created, is set at installation time.
  • CASCD0029I
    This exit provides external control for starting CAS server instances. It will be given control each time the console daemon wants to start a new server instance.
  • CASCD0030I
    Console daemon forwarded a server instance start request to the casexitv exit program and casexitv returned with a non-zero return code of return-code.
  • CASCD0031I
    A server has been started for region region-name. server-number server start requests have been issued.
Parent topic: CASCD Error Messages


CASCD0016W

The region name specified on the command line to dfhtxs to auto-start was found to be invalid. If the region can not be located under $CASDIR or appropriate REGIONBASE directory then it is removed from the auto-start region list.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will be removed from the auto-start list and the console will continue its initialization.
Resolution:
Check the spelling of the region name and appropriate REGIONBASE settings, including character case if on UNIX. If the name is incorrect then the region can be started immediately via dfhrem.
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0016 - CASCD0031


CASCD0022E

There is no CAS Daemon to shutdown.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Ensure an CAS Daemon is running before attempting shutdown
Destination:
standard error
Module:
dfhtxp
Parent topic: CASCD0016 - CASCD0031


CASCD0023S

The specified option is not valid
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Retry the request with a valid option
Destination:
standard error
Module:
dfhtxp
Parent topic: CASCD0016 - CASCD0031


CASCD0024S

Too many arguments were specified, the maximum permitted is 1.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Retry the request with the correct number of arguments
Destination:
standard error
Module:
dfhtxp
Parent topic: CASCD0016 - CASCD0031


CASCD0025S

A UNIX call returned with errno set to errnoThe call that failed is specified by errno, where: 1 = msgget 2 = msgsnd 3 = fgets 4 = fopen 5 = mknod
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS Daemon is not shut down
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
standard error
Module:
dfhtxp
Parent topic: CASCD0016 - CASCD0031


CASCD0026S

The CAS Daemon did not respond to the shutdown request, it is not possible to determine the current state of the daemon
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
standard error
Module:
dfhtxp
Parent topic: CASCD0016 - CASCD0031


CASCD0027W

The immediate shutdown option of the console daemon shutdown utility abends all running regions. Data may be lost or the system may be left in an unstable state. This option should only be used as a last resort. It is recommended that each region is shutdown cleanly before using the dfhtxp command.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Console daemon shutdown will continue
Destination:
Console and stdout
Module:
dfhtxp
Parent topic: CASCD0016 - CASCD0031


CASCD0028I

If the CAS Console Daemon is not running with the effective user ID of root (UID=0) this message details the current effective user id. The effective user ID that the CAS console Daemon runs as, and all region created, is set at installation time.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
Console
Module:
dfhmd
Parent topic: CASCD0016 - CASCD0031


CASCD0029I

This exit provides external control for starting CAS server instances. It will be given control each time the console daemon wants to start a new server instance.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
Console
Module:
dfhmd
Parent topic: CASCD0016 - CASCD0031


CASCD0030I

Console daemon forwarded a server instance start request to the casexitv exit program and casexitv returned with a non-zero return code of return-code.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None - the exit is responsible for starting the requested server instance
Resolution:
Take action approprate to the exit program's return code
Destination:
Console
Module:
dfhmd
Parent topic: CASCD0016 - CASCD0031


CASCD0031I

A server has been started for region region-name. server-number server start requests have been issued.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0016 - CASCD0031


CASCD0050 - CASCD0099

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD0050I
    The region initiation has been started. Client connection will not be immediately available. Check the console log to determine if the region completed initiation successfully.
  • CASCD0051F
    The request to start a region was not successful
  • CASCD0052S
    An attempt has been made to start a region before there is an active CAS Daemon
  • CASCD0053S
    The REM has sent no progress messages, its state is not known
  • CASCD0054S
    A UNIX call returned with errno set to errno.
  • CASCD0060I
    The server has been started.
  • CASCD0061F
    The request to start a server was not successful
  • CASCD0062S
    An attempt has been made to start a server before there is an active CAS Daemon
  • CASCD0063S
    The server has sent no progress messages, its state is not known
  • CASCD0064S
    A UNIX call returned with errno set to errno.
  • CASCD0099I
    The CAS Daemon tag for current version
Parent topic: CASCD Error Messages


CASCD0050I

The region initiation has been started. Client connection will not be immediately available. Check the console log to determine if the region completed initiation successfully.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
standard error
Module:
dfhrem
Parent topic: CASCD0050 - CASCD0099


CASCD0051F

The request to start a region was not successful
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region is not started
Resolution:
Check previous messages for cause of error, correct the problem and retry if appropriate
Destination:
standard error
Module:
dfhrem
Parent topic: CASCD0050 - CASCD0099


CASCD0052S

An attempt has been made to start a region before there is an active CAS Daemon
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region is not started
Resolution:
Start an CAS Daemon before attempting to start other components
Destination:
standard error
Module:
dfhrem
Parent topic: CASCD0050 - CASCD0099


CASCD0053S

The REM has sent no progress messages, its state is not known
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
standard error
Module:
dfhrem
Parent topic: CASCD0050 - CASCD0099


CASCD0054S

A UNIX call returned with errno set to errno.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The call that failed is specified by errno, where:

  • 1 = msgget
  • 2 = msgsnd
  • 3 = fgets
  • 4 = fopen
  • 5 = mknod
System Action:
The region is not started
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
standard error
Module:
dfhtxp
Parent topic: CASCD0050 - CASCD0099


CASCD0060I

The server has been started.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
standard error
Module:
dfhserv
Parent topic: CASCD0050 - CASCD0099


CASCD0061F

The request to start a server was not successful
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The server is not started
Resolution:
Check previous messages for cause of error, correct the problem and retry if appropriate
Destination:
standard error
Module:
dfhserv
Parent topic: CASCD0050 - CASCD0099


CASCD0062S

An attempt has been made to start a server before there is an active CAS Daemon
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The server is not started
Resolution:
Start an CAS Daemon before attempting to start other components
Destination:
standard error
Module:
dfhserv
Parent topic: CASCD0050 - CASCD0099


CASCD0063S

The server has sent no progress messages, its state is not known
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
standard error
Module:
dfhserv
Parent topic: CASCD0050 - CASCD0099


CASCD0064S

A UNIX call returned with errno set to errno.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The call that failed is specified by errno, where:

System Action:
The CAS Daemon is not shut down
Resolution:
Determine the cause of the error and retry if appropriate
Destination:
standard error
Module:
dfhtxp
Parent topic: CASCD0050 - CASCD0099


CASCD0099I

The CAS Daemon tag for current version
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0050 - CASCD0099


CASCD0100 - CASCD0117

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD0100I
    The CAS Daemon has initialized and is waiting for work
  • CASCD0101I
    The CAS Daemon has completed termination
  • CASCD0102F
    The CAS Daemon has failed to initialize
  • CASCD0103E
    The CAS Daemon has received a message with an unknown request type of Request-Type
  • CASCD0104I
    The ES Daemon has initialized and is waiting for work
  • CASCD0110I
    The CAS Daemon is beginning a normal shutdown
  • CASCD0111I
    The CAS Daemon is beginning an orderly shutdown and will wait for the number-of-regions regions to terminate before shutting down
  • CASCD0112I
    The CAS Daemon is beginning an immediate shutdown and will abend number-of-regions regions before shutting down
  • CASCD0113I
    The CAS Daemon has terminated
  • CASCD0114W
    The CAS Daemon cannot begin a normal shutdown while there are regions running
  • CASCD0115E
    The CAS Daemon was already shutting down when this request was received
  • CASCD0116I
    The CAS Daemon was in a normal or orderly shutdown already, but will now shutdown immediately
  • CASCD0117S
    A UNIX call returned with errno set to errno during quiesce of the CAS Daemon.
Parent topic: CASCD Error Messages


CASCD0100I

The CAS Daemon has initialized and is waiting for work
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0101I

The CAS Daemon has completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0102F

The CAS Daemon has failed to initialize
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The CAS daemon is not started
Resolution:
Check previous messages for cause of error, correct the problem and retry if appropriate
Destination:
standard error
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0103E

The CAS Daemon has received a message with an unknown request type of Request-Type
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is ignored
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0104I

The ES Daemon has initialized and is waiting for work
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
standard error and system console
Module:
cascd
Parent topic: CASCD0100 - CASCD0117


CASCD0110I

The CAS Daemon is beginning a normal shutdown
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Shutdown
Resolution:
none
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0111I

The CAS Daemon is beginning an orderly shutdown and will wait for the number-of-regions regions to terminate before shutting down
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Wait for regions then shutdown
Resolution:
None
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0112I

The CAS Daemon is beginning an immediate shutdown and will abend number-of-regions regions before shutting down
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Abend the regions then shutdown
Resolution:
None
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0113I

The CAS Daemon has terminated
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0114W

The CAS Daemon cannot begin a normal shutdown while there are regions running
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The shutdown request is rejected
Resolution:
Shutdown the active regions and retry
Destination:
standard error
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0115E

The CAS Daemon was already shutting down when this request was received
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Ignore the redundant shutdown request
Resolution:
None
Destination:
standard error
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0116I

The CAS Daemon was in a normal or orderly shutdown already, but will now shutdown immediately
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Immediate shutdown
Resolution:
None
Destination:
standard error
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0117S

A UNIX call returned with errno set to errno during quiesce of the CAS Daemon.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The call that failed is specified by function, where:

  • 1 = msgget
  • 2 = msgsnd
  • 3 = fgets
  • 4 = fopen
  • 5 = mknod
System Action:
The CAS Daemon continues shutdown
Resolution:
Dependent on value of errno
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0100 - CASCD0117


CASCD0120 - CASCD0139

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD0120I
    The REM for region region-name has been started. It will run with a process-id of pid
  • CASCD0122E
    An attempt was made to start a region or server when the system was shutting down
  • CASCD0123E
    An attempt was made to start a region (region-name) for which a REM was already running
  • CASCD0124E
    An attempt was made to start a server for a region which is not active
  • CASCD0125I
    CAS attempted to exec executable-name, but the call failed with errno errno
  • CASCD0126I
    CAS attempted to fork a new process from the CAS Daemon process but the call failed with errno errno
  • CASCD0127I
    A server has been started for region region-name, it is the server-number server to be started for that region and will run with a process-id of pid
  • CASCD0128I
    The 3270 printer service has been started for region region-name
  • CASCD0129I
    The 3270 CCI gateway service has been started for region region-name
  • CASCD0130I
    Region region-name has successfully completed termination
  • CASCD0131I
    Server server-number of region region-name has successfully completed termination
  • CASCD0132I
    The 3270 printer service for region region-namehas successfully completed termination
  • CASCD0133I
    The 3270 CCI gateway service for region region-namehas successfully completed termination
  • CASCD0134I
    CAS attempted to exec dfhgdied, but the call failed with errno errno
  • CASCD0135I
    CAS attempted to fork a new process from the CAS Daemon process but the call failed with errno errno
  • CASCD0136W
    CAS attempted to exec dfhgrtrm, but the call failed with errno errno
  • CASCD0137W
    The CAS Daemon process created a child process which could failed in initialization due to a failed 'execlp' call.
  • CASCD0138F
    CAS attempted to exec dfhgrtrm, but the call failed with errno errno
  • CASCD0139I
    The CAS Daemon was started automatically as part of region startup. No regions are active so the CAS Daemon is automatically terminating.
Parent topic: CASCD Error Messages


CASCD0120I

The REM for region region-name has been started. It will run with a process-id of pid
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0122E

An attempt was made to start a region or server when the system was shutting down
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Do not attempt to start regions or servers during shutdown
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0123E

An attempt was made to start a region (region-name) for which a REM was already running
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Retry with a valid region name (if required)
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0124E

An attempt was made to start a server for a region which is not active
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Start the REM for region-name before attempting to start servers again
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0125I

CAS attempted to exec executable-name, but the call failed with errno errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the new process and abort the attempt to start a REM or server
Resolution:
Determine and fix cause of failure then retry
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0126I

CAS attempted to fork a new process from the CAS Daemon process but the call failed with errno errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Abort the attempt to start a REM or server
Resolution:
Determine and fix cause of failure then retry
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0127I

A server has been started for region region-name, it is the server-number server to be started for that region and will run with a process-id of pid
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0128I

The 3270 printer service has been started for region region-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0129I

The 3270 CCI gateway service has been started for region region-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0130I

Region region-name has successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0131I

Server server-number of region region-name has successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0132I

The 3270 printer service for region region-namehas successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0133I

The 3270 CCI gateway service for region region-namehas successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0134I

CAS attempted to exec dfhgdied, but the call failed with errno errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the new process and abort the attempt to inform the region manager of the process which has terminated
Resolution:
Determine and fix cause of failure then retry
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0135I

CAS attempted to fork a new process from the CAS Daemon process but the call failed with errno errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Abort the attempt to inform the region manager of a terminated process
Resolution:
Determine and fix cause of failure then retry
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0136W

CAS attempted to exec dfhgrtrm, but the call failed with errno errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the new process and abort the attempt to terminate a region. The region will continue to run.
Resolution:
Determine and fix cause of failure then retry
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0137W

The CAS Daemon process created a child process which could failed in initialization due to a failed 'execlp' call.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the child process
Resolution:
Determine and fix cause of failure then retry
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0138F

CAS attempted to exec dfhgrtrm, but the call failed with errno errno
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the new process and abort the attempt to terminate a region. The region will continue to run.
Resolution:
Determine and fix cause of failure then retry
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0139I

The CAS Daemon was started automatically as part of region startup. No regions are active so the CAS Daemon is automatically terminating.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Shutdown
Resolution:
None
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0120 - CASCD0139


CASCD0141 - CASCD0159

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD0141S
    Region region-name has failed to initialize and exited, the value specified on the exit call was exit-value
  • CASCD0142S
    Region region-name has ended abnormally with an exit call, the value specified on the exit call was exit-value
  • CASCD0143S
    Region region-name has ended abnormally during termination with an exit call, the value specified on the exit call was exit-value
  • CASCD0144S
    server server-number of region region-name has failed to initialize and exited, the value specified on the exit call was exit-value
  • CASCD0145S
    The 3270 printer service of region region-name has exited, the value specified on the exit call was exit-value
  • CASCD0146S
    The 3270 CCI gateway of region region-name has exited, the value specified on the exit call was exit-value
  • CASCD0151S
    Region region-name has abended during initialization due to receipt of signal signal-value
  • CASCD0152S
    Region region-name has abended during normal execution due to receipt of signal signal-value
  • CASCD0153S
    Region region-name has abended during termination due to receipt of signal signal-value
  • CASCD0154S
    server server-number of region region-name has abended due to receipt of signal signal-value
  • CASCD0155S
    The 3270 printer service of region region-name has abended due to receipt of signal signal-value
  • CASCD0156S
    The 3270 CCI gateway of region region-name has abended due to receipt of signal signal-value
  • CASCD0157E
    An error occurred in the CCI communications of the CAS console daemon. CCI-error-text is returned from CCI. This message will be generated prior to message CASCD0158E for CCI error return code 9.
  • CASCD0158E
    An error occurred in the CCI communications of the CAS console daemon.
  • CASCD0159F
    Only one CAS Daemon is required, attempts to start more are rejected
Parent topic: CASCD Error Messages


CASCD0141S

Region region-name has failed to initialize and exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0142S

Region region-name has ended abnormally with an exit call, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0143S

Region region-name has ended abnormally during termination with an exit call, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0144S

server server-number of region region-name has failed to initialize and exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0145S

The 3270 printer service of region region-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0146S

The 3270 CCI gateway of region region-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0151S

Region region-name has abended during initialization due to receipt of signal signal-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0152S

Region region-name has abended during normal execution due to receipt of signal signal-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0153S

Region region-name has abended during termination due to receipt of signal signal-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0154S

server server-number of region region-name has abended due to receipt of signal signal-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0155S

The 3270 printer service of region region-name has abended due to receipt of signal signal-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0156S

The 3270 CCI gateway of region region-name has abended due to receipt of signal signal-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0157E

An error occurred in the CCI communications of the CAS console daemon. CCI-error-text is returned from CCI. This message will be generated prior to message CASCD0158E for CCI error return code 9.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0158E

An error occurred in the CCI communications of the CAS console daemon.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Some common values for CCI-error are:

  • 2 - Comms buffer too small for received message
  • 3 - Invalid session identifier given
  • 4 - Server of same name already defined (warning)
  • 5 - Server of same name already defined (error)
  • 6 - Invalid public or machine name
  • 7 - Invalid request on closed session
  • 8 - Previous connection not responding
  • 9 - Miscellaneous error
  • 10 - Request could not be executed
  • 11 - Run out of memory
  • 12 - Unknown error
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhmd
Parent topic: CASCD0141 - CASCD0159


CASCD0159F

Only one CAS Daemon is required, attempts to start more are rejected
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Terminate existing Daemon if restart is required
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0141 - CASCD0159


CASCD0160 - CASCD0175

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD0160F
    The DosStartSession failed with the return code error-id. This code may be an error listed with DosStartSession, DosOpen, DosLoadModule, or DosExecPgm. The module being started is dfhmd.exe in directory $CASDIR\lib.
  • CASCD0161I
    The CAS Daemon has initialized and is waiting for work
  • CASCD0162S
    The journal control service for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0163S
    The extra partition transient data service for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0164S
    The FS service for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0165W
    CAS attempted to create a new process from the CAS Daemon process but the call failed with RC=return-code from a DosExecPgm request.
  • CASCD0166W
    CAS attempted to create a new process from the CAS Daemon process but the call failed with RC=return-code from a CreateProcess request.
  • CASCD0167I
    The CAS daemon was not active when the start region request was issued. The CAS daemon was automatically started.
  • CASCD0168S
    The Spool service for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0169S
    The CAS gateway for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0170S
    A process for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0171S
    The MQSeries gateway for region region-name has abended due to an unexpected signal signal-value.
  • CASCD0172S
    The ES Console Process failed because it does not have the required threading support.
  • CASCD0173S
    The ES Console tried to start a receive-all thread. The create-thread operation failed with a return code of return-code
  • CASCD0174I
    The ES Console thread that handles process terminations has exited normally.
  • CASCD0175I
    Processing of ddbg port range detected an error Verify region configuration.
Parent topic: CASCD Error Messages


CASCD0160F

The DosStartSession failed with the return code error-id. This code may be an error listed with DosStartSession, DosOpen, DosLoadModule, or DosExecPgm. The module being started is dfhmd.exe in directory $CASDIR\lib.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The request is rejected
Resolution:
Correct the cause of the return code error-id
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0160 - CASCD0175


CASCD0161I

The CAS Daemon has initialized and is waiting for work
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
standard error
Module:
dfhtxs
Parent topic: CASCD0160 - CASCD0175


CASCD0162S

The journal control service for region region-name has abended due to the unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0163S

The extra partition transient data service for region region-name has abended due to the unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0164S

The FS service for region region-name has abended due to the unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0165W

CAS attempted to create a new process from the CAS Daemon process but the call failed with RC=return-code from a DosExecPgm request.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Abort the attempt to start a REM or server
Resolution:
Determine and fix cause of failure then retry
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0166W

CAS attempted to create a new process from the CAS Daemon process but the call failed with RC=return-code from a CreateProcess request.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Abort the attempt to start a REM or server
Resolution:
Determine and fix cause of failure then retry
Destination:
standard error and system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0167I

The CAS daemon was not active when the start region request was issued. The CAS daemon was automatically started.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Start CAS daemon
Resolution:
None
Destination:
standard error
Module:
dfhrem
Parent topic: CASCD0160 - CASCD0175


CASCD0168S

The Spool service for region region-name has abended due to the unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0169S

The CAS gateway for region region-name has abended due to the unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0170S

A process for region region-name has abended due to the unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0171S

The MQSeries gateway for region region-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD0160 - CASCD0175


CASCD0172S

The ES Console Process failed because it does not have the required threading support.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The Enterprise Server is not started
Resolution:
Report the failure to Micro Focus Support
Destination:
system console
Module:
cascd
Parent topic: CASCD0160 - CASCD0175


CASCD0173S

The ES Console tried to start a receive-all thread. The create-thread operation failed with a return code of return-code
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Resolution:
Report the failure to Micro Focus Support
Destination:
system console
Module:
cascd
Parent topic: CASCD0160 - CASCD0175


CASCD0174I

The ES Console thread that handles process terminations has exited normally.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
cascd
Parent topic: CASCD0160 - CASCD0175


CASCD0175I

Processing of ddbg port range detected an error Verify region configuration.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Resolution:
Port range processing is disabled, unless no more port available. Verify configuration and correct error
Destination:
system console
Module:
cascd
Parent topic: CASCD0160 - CASCD0175


CASCD1001 - CASCD1056

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD1001S
    An error occurred locating the region directory for region region-name. Either the region is not defined or environment variable CASDIR is pointing to the wrong place.
  • CASCD1002S
    An error occurred locating the target directory for the region work files.
  • CASCD1003S
    An error occurred locating the target directory for the system work files.
  • CASCD1004S
    An error occurred setting up the environment variables for the region. The return code from the function is reason-code.
  • CASCD1010S
    An error occurred whilst processing the global configuration file.
  • CASCD1011S
    An error occurred while processing the region configuration file.
  • CASCD1020I
    The JCP service has been started for region region-name
  • CASCD1031S
    The ODBC service process of region region-name has exited, the value specified on the exit call was exit-value
  • CASCD1032I
    A MQSeries Gateway has been started for region region-name This gateway emulates the CKTI trigger monitor transaction.
  • CASCD1033I
    The MQSeries Gateway service process for region region-name has successfully completed termination
  • CASCD1034S
    The MQSeries Gateway process of region region-name has exited, the value specified on the exit call was exit-value
  • CASCD1035I
    A Spool service has been started for region region-name
  • CASCD1036I
    The Spool service process for region region-name has successfully completed termination
  • CASCD1037S
    The Spool service of region region-name has exited, the value specified on the exit call was exit-value
  • CASCD1038I
    An ES Communications Server has been started for ES region-name
  • CASCD1039I
    The ES Communications Server process for ES region-name has successfully completed termination
  • CASCD1040S
    The ES Communication Server of ES region-name has exited, the value specified on the exit call was exit-value
  • CASCD1041S
    The ES Console was notified of a process death that it did not know about. This should not occur.
  • CASCD1044I IMS DB Control Process for Service execution process service execution process-name has terminated normally
    The IMS DB Control Process for Service execution process service execution process-name has successfully completed termination.
  • CASCD1045S IMS DB Control Process for Service execution process service execution process-name exited with value exit-value
    The IMS DB Control Process for Service execution process service execution process-name has exited, the value specified on the exit call was exit-value.
  • CASCD1046S IMS TM Control Process for Service execution process service execution process-name abended by signal signal-value
    The IMS TM Control Process for Service execution process service execution process-name has abended due to an unexpected signal signal-value.
  • CASCD1047S IMS DB Control Process for Service execution process service execution process-name abended by signal signal-value
    The IMS TM Control Process for Service execution process service execution process-name has abended due to an unexpected signal signal-value.
  • CASCD1048I IMS TM Control Process for Service execution process server-name has terminated normally
    The IMS TM Control Process for Service execution process server-name has successfully completed termination.
  • CASCD1049S IMS TM Control Process for Service execution process server-name exited with value exit-value
    The IMS TM Control Process for Service execution process server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1050I IMS MPR Process for Service execution process service execution process-name has terminated normally
    An IMS MPR Process for Service execution process service execution process-name has successfully completed termination.
  • CASCD1051S IMS MPR Process for Service execution process service execution process-name exited with value exit-value
    An IMS MPR Process for Service execution process service execution process-name has exited, the value specified on the exit call was exit-value.
  • CASCD1052I JES Initiator for Service execution process service execution process-name has terminated normally
    A JES Initiator for service execution process service execution process-name has successfully completed termination.
  • CASCD1053S JES Initiator for Service execution process service execution process-name exited with value exit-value
    A JES Initiator for Service execution process service execution process-name has exited, the value specified on the exit call was exit-value.
  • CASCD1054I JES Printer for Service execution process service execution process-name has terminated normally
    A JES Printer for Service execution process service execution process-name has successfully completed termination.
  • CASCD1055S JES Printer for Service execution process service execution process-name exited with value exit-value
    A JES Printer for Service execution process service execution process-name has exited, the value specified on the exit call was exit-value.
  • CASCD1056S IMS MPR Process for Service execution process service execution process-name abended by signal signal-value
    An IMS MPR Process for Service execution process service execution process-name has abended due to an unexpected signal signal-value.
Parent topic: CASCD Error Messages


CASCD1001S

An error occurred locating the region directory for region region-name. Either the region is not defined or environment variable CASDIR is pointing to the wrong place.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region start request is not processed
Resolution:
Correct the setting of CASDIR, correct region-name, or define the region
Destination:
standard out
Module:
dfhrem
Parent topic: CASCD1001 - CASCD1056


CASCD1002S

An error occurred locating the target directory for the region work files.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region start request is not processed
Resolution:
Correct the region setup or define the region
Destination:
standard out
Module:
dfhrem
Parent topic: CASCD1001 - CASCD1056


CASCD1003S

An error occurred locating the target directory for the system work files.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region start request is not processed
Resolution:
Correct the region setup or define the region
Destination:
standard out
Module:
dfhrem
Parent topic: CASCD1001 - CASCD1056


CASCD1004S

An error occurred setting up the environment variables for the region. The return code from the function is reason-code.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region start request is not processed
Resolution:
Correct the installation of Transaction System
Destination:
standard out
Module:
dfhrem
Parent topic: CASCD1001 - CASCD1056


CASCD1010S

An error occurred whilst processing the global configuration file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region manager will not initialize successfully
Resolution:
Correct the fault with the configuration file
Destination:
console
Module:
dfhrem
Parent topic: CASCD1001 - CASCD1056


CASCD1011S

An error occurred while processing the region configuration file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The console daemon or region manager will not initialize successfully
Resolution:
Correct the fault with the configuration file
Destination:
console
Module:
dfhrem
Parent topic: CASCD1001 - CASCD1056


CASCD1020I

The JCP service has been started for region region-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1031S

The ODBC service process of region region-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1032I

A MQSeries Gateway has been started for region region-name This gateway emulates the CKTI trigger monitor transaction.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1033I

The MQSeries Gateway service process for region region-name has successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1034S

The MQSeries Gateway process of region region-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1035I

A Spool service has been started for region region-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1036I

The Spool service process for region region-name has successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1037S

The Spool service of region region-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1038I

An ES Communications Server has been started for ES region-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1039I

The ES Communications Server process for ES region-name has successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1040S

The ES Communication Server of ES region-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1041S

The ES Console was notified of a process death that it did not know about. This should not occur.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1001 - CASCD1056


CASCD1044I IMS DB Control Process for Service execution process service execution process-name has terminated normally

The IMS DB Control Process for Service execution process service execution process-name has successfully completed termination.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1045S IMS DB Control Process for Service execution process service execution process-name exited with value exit-value

The IMS DB Control Process for Service execution process service execution process-name has exited, the value specified on the exit call was exit-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1046S IMS TM Control Process for Service execution process service execution process-name abended by signal signal-value

The IMS TM Control Process for Service execution process service execution process-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1047S IMS DB Control Process for Service execution process service execution process-name abended by signal signal-value

The IMS TM Control Process for Service execution process service execution process-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1048I IMS TM Control Process for Service execution process server-name has terminated normally

The IMS TM Control Process for Service execution process server-name has successfully completed termination.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1049S IMS TM Control Process for Service execution process server-name exited with value exit-value

The IMS TM Control Process for Service execution process server-name has exited, the value specified on the exit call was exit-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1050I IMS MPR Process for Service execution process service execution process-name has terminated normally

An IMS MPR Process for Service execution process service execution process-name has successfully completed termination.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1051S IMS MPR Process for Service execution process service execution process-name exited with value exit-value

An IMS MPR Process for Service execution process service execution process-name has exited, the value specified on the exit call was exit-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1052I JES Initiator for Service execution process service execution process-name has terminated normally

A JES Initiator for service execution process service execution process-name has successfully completed termination.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1053S JES Initiator for Service execution process service execution process-name exited with value exit-value

A JES Initiator for Service execution process service execution process-name has exited, the value specified on the exit call was exit-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1054I JES Printer for Service execution process service execution process-name has terminated normally

A JES Printer for Service execution process service execution process-name has successfully completed termination.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1055S JES Printer for Service execution process service execution process-name exited with value exit-value

A JES Printer for Service execution process service execution process-name has exited, the value specified on the exit call was exit-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1056S IMS MPR Process for Service execution process service execution process-name abended by signal signal-value

An IMS MPR Process for Service execution process service execution process-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Parent topic: CASCD1001 - CASCD1056


CASCD1057 - CASCD1069

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD1061S
    An undefined process request was received for Server server-name
  • CASCD1062I
    A JES Printer Process has been started for Server server-name
  • CASCD1063I
    An Event Manager Process has been started for Server server-name
  • CASCD1064I
    An Event Manager for Server server-name has successfully completed termination
  • CASCD1065S
    An Event Manager for Server server-name has exited, the value specified on the exit call was exit-value
  • CASCD1066S
    An Event Manager for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1067I
    An Animserv process has been started for Server server-name
  • CASCD1068I
    An Animserv process for Server server-name has successfully terminated
  • CASCD1069S
    An Animserv process for Server server-name has exited, the value specified on the exit call was exit-value
Parent topic: CASCD Error Messages


CASCD1061S

An undefined process request was received for Server server-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Continue
Resolution:
Evaluate the impact of the error and take approprate action
Destination:
Console and standard error
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1062I

A JES Printer Process has been started for Server server-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1063I

An Event Manager Process has been started for Server server-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1064I

An Event Manager for Server server-name has successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1065S

An Event Manager for Server server-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1066S

An Event Manager for Server server-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1067I

An Animserv process has been started for Server server-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1068I

An Animserv process for Server server-name has successfully terminated
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1069S

An Animserv process for Server server-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1057 - CASCD1069


CASCD1070 - CASCD1200

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD1070S
    An Animserv process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1071I
    An administration SEP has been started for Server server-name
  • CASCD1072I
    An administration SEP has been started for Server server-namehas successfully completed termination
  • CASCD1073S
    An administration SEP for Server server-name has exited, the value specified on the exit call was exit-value
  • CASCD1074S
    An administration SEP for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1075I
    The ES TSC Service Process has been started for Server server-name
  • CASCD1076I
    The ES TSC Service Process for Server server-name has successfully completed termination
  • CASCD1077S
    The ES TSC Service Process for Server server-name has exited, the value specified on the exit call was exit-value
  • CASCD1078S
    The IMS TM Control Process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1079I
    A Cobremotedaemon process has been started for Server server-name
  • CASCD1080I
    A Cobremotedaemon process for Server server-name has successfully terminated
  • CASCD1081S
    A Cobremotedaemon process for Server server-name has exited, the value specified on the exit call was exit-value
  • CASCD1082S
    A Cobremotedaemon process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1083I
    Enterprise Server Debug SEP created successfully.
  • CASCD1084I
    A Debug SEP for Server server-namehas successfully completed termination
  • CASCD1085S
    A Debug SEP for Server server-name has exited, the value specified on the exit call was exit-value
  • CASCD1086S
    A Debug SEP for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1087I Cobdebugremote process created for Server server-name, process-id = pid
    A Cobdebugremote process has been started for Server server-name.
  • CASCD1088S Cobdebugremote process for Server server-name abended by signal signal-value
    A Cobdebugremote process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1089I Cobdebugremote process for Server server-name has terminated normally
    An Cobdebugremote process for Server server-name has successfully terminated.
  • CASCD1090S Cobdebugremote process for Server server-name exited with value exit-value
    An Cobdebugremote process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1200I
    The transaction transaction-id issued a SPOOLOPEN command but did not issue a subsequent SPOOLCLOSE command before transaction termination.
Parent topic: CASCD Error Messages


CASCD1070S

An Animserv process for Server server-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1071I

An administration SEP has been started for Server server-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1072I

An administration SEP has been started for Server server-namehas successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1073S

An administration SEP for Server server-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1074S

An administration SEP for Server server-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1075I

The ES TSC Service Process has been started for Server server-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1076I

The ES TSC Service Process for Server server-name has successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1077S

The ES TSC Service Process for Server server-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1078S

The IMS TM Control Process for Server server-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1079I

A Cobremotedaemon process has been started for Server server-name
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1080I

A Cobremotedaemon process for Server server-name has successfully terminated
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1081S

A Cobremotedaemon process for Server server-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1082S

A Cobremotedaemon process for Server server-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1083I

Enterprise Server Debug SEP created successfully.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1084I

A Debug SEP for Server server-namehas successfully completed termination
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1085S

A Debug SEP for Server server-name has exited, the value specified on the exit call was exit-value
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1086S

A Debug SEP for Server server-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
system console
Module:
dfhmd
Parent topic: CASCD1070 - CASCD1200


CASCD1087I Cobdebugremote process created for Server server-name, process-id = pid

A Cobdebugremote process has been started for Server server-name.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: CASCD1070 - CASCD1200


CASCD1088S Cobdebugremote process for Server server-name abended by signal signal-value

A Cobdebugremote process for Server server-name has abended due to an unexpected signal signal-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: CASCD1070 - CASCD1200


CASCD1089I Cobdebugremote process for Server server-name has terminated normally

An Cobdebugremote process for Server server-name has successfully terminated.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: CASCD1070 - CASCD1200


CASCD1090S Cobdebugremote process for Server server-name exited with value exit-value

An Cobdebugremote process for Server server-name has exited, the value specified on the exit call was exit-value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
cascd
Destination:
system console
Parent topic: CASCD1070 - CASCD1200


CASCD1200I

The transaction transaction-id issued a SPOOLOPEN command but did not issue a subsequent SPOOLCLOSE command before transaction termination.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
A SPOOLCLOSE command is assumed
Resolution:
A SPOOLCLOSE command is assumed
Destination:
console
Module:
dfhesysp
Parent topic: CASCD1070 - CASCD1200


CASCD4002 - CASCD4007

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCD4002W
    An error occured whilst binding to the MF Directory Server.
  • CASCD4003W
    An error occured whilst retrieving the ES configuration from the MF Directory Server.
  • CASCD4004W
    An error occured whilst binding to the MF Directory Server.
  • CASCD4005I
    Messages to CAS Deamon will be logged to the windows event log.
  • CASCD4006I
    Messages to CAS Deamon will not be logged to the windows event log.
  • CASCD4007E
    Error error-message when trying to log to the windows event log.
Parent topic: CASCD Error Messages


CASCD4002W

An error occured whilst binding to the MF Directory Server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Continue initialization using defaults
Resolution:
None
Destination:
Console and standard error
Module:
dfhmd
Parent topic: CASCD4002 - CASCD4007


CASCD4003W

An error occured whilst retrieving the ES configuration from the MF Directory Server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Continue initialization using defaults
Resolution:
None
Destination:
console and standard error
Module:
dfhmd
Parent topic: CASCD4002 - CASCD4007


CASCD4004W

An error occured whilst binding to the MF Directory Server.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Continue initialization using defaults
Resolution:
None
Destination:
Console and standard error
Module:
dfhmd
Parent topic: CASCD4002 - CASCD4007


CASCD4005I

Messages to CAS Deamon will be logged to the windows event log.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
Console and standard error
Module:
dfhmd
Parent topic: CASCD4002 - CASCD4007


CASCD4006I

Messages to CAS Deamon will not be logged to the windows event log.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
Console and standard error
Module:
dfhmd
Parent topic: CASCD4002 - CASCD4007


CASCD4007E

Error error-message when trying to log to the windows event log.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
SYSACTION
Resolution:
Report the error to technical support
Destination:
console and standard error
Module:
dfhmd
Parent topic: CASCD4002 - CASCD4007


CASCF Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCF0001 - CASCF0015
  • CASCF0016 - CASCF0030
  • CASCF0031 - CASCF0045
  • CASCF0046 - CASCF0064
Parent topic: Enterprise Server Error Messages


CASCF0001 - CASCF0015

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCF0001F
    An error has occurred during Region configuration file processing Refer to CASCF0002F for the possible values of RC-1 and RC-2
  • CASCF0002F
    An error has occurred during Region configuration file processing.
  • CASCF0003F
    The messaging support module could not be loaded as part of system initialization. This module is required for normal system operation.
  • CASCF0004F
    The configuration support module could not be loaded as part of system initialization. This module is required for normal system operation.
  • CASCF0005F
    The utility support module could not be loaded as part of system initialization. This module is required for normal system operation.
  • CASCF0006F
    The file handling support module could not be loaded as part of system initialization. This module is required for normal system operation.
  • CASCF0007F
    The file handling support module could not be loaded as part of system initialization. This module is required for normal system operation.
  • CASCF0008F
    An unexpected error occurred in system initialization while processing the configuration file.
  • CASCF0010S
    An unrecognized line was found in the global configuration file ($CASDIR/dfhtx.cfg) at the line shown.
  • CASCF0011S
    An unrecognized line was found in the region configuration file ($REGIONBASE/$CASREGN/dfhtx.cfg) at the line shown.
  • CASCF0012S
    An unrecognized line was found in the development configuration file (dfhtxdev.cfg) at the line shown.
  • CASCF0013S
    The global configuration file ($CASDIR/dfhtx.cfg) could not located.
  • CASCF0014S
    The region configuration file ($REGIONBASE/$CASREGN/dfhtx.cfg) could not be located.
  • CASCF0015S
    The development configuration file (dfhtxdev.cfg) could not be located.
Parent topic: CASCF Error Messages


CASCF0001F

An error has occurred during Region configuration file processing Refer to CASCF0002F for the possible values of RC-1 and RC-2
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Determine and fix the cause of the problem
Destination:
standard error and/or system console
Module:
dfh0cfg
Parent topic: CASCF0001 - CASCF0015


CASCF0002F

An error has occurred during Region configuration file processing.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The error-type describes the type of error, and error-qualifier gives further information depending on error-type as follows:

  • 1 - The region name (error-qualifier) was not valid
  • 2 - Line number error-qualifier of the configuration file is not valid
  • 3 - The configuration file did not exist when OPEN was called, error-qualifier contains the COBOL return code from CBL_OPEN_FILE
  • 4 - Failure when creating configuration save file, error-qualifier contains COBOL return code from CBL_CREATE_FILE
  • 5 - Failure reading from file, error-qualifier contains the COBOL return code from CBL_READ_FILE
  • 6 - Failure writing to file, error-qualifier contains the COBOL return code from CBL_WRITE_FILE
System Action:
Terminate the requesting process
Resolution:
Determine and fix the cause of the problem
Destination:
standard error and/or system console
Module:
dfh0cfg
Parent topic: CASCF0001 - CASCF0015


CASCF0003F

The messaging support module could not be loaded as part of system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that $CASDIR is set correctly and the module dfh0msg exists in $CASDIR/lib
standard error
DEST
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0001 - CASCF0015


CASCF0004F

The configuration support module could not be loaded as part of system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that $CASDIR is set correctly and the module dfh0cfg exists in $CASDIR/lib
Destination:
standard error
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0001 - CASCF0015


CASCF0005F

The utility support module could not be loaded as part of system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that $CASDIR is set correctly and the module dfh0utl exists in $CASDIR/lib
Destination:
standard error
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0001 - CASCF0015


CASCF0006F

The file handling support module could not be loaded as part of system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that $CASDIR is set correctly and the module dfhextfh exists in $CASDIR/lib.
Destination:
standard error
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0001 - CASCF0015


CASCF0007F

The file handling support module could not be loaded as part of system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that $CASDIR is set correctly and the module mffh exists in $COBDIR
Destination:
standard error
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0001 - CASCF0015


CASCF0008F

An unexpected error occurred in system initialization while processing the configuration file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Some values for RC are:

  • 01 - No region name specified
  • 02 - Bad line in file
  • 03 - File not found
  • 04 - Error creating file
  • 05 - Error opening file
  • 06 - Error reading file
  • 07 - Error writing to file
  • 08 - CASLOCAL invalid
  • 09 - CASDIR invalid
  • 10 - Region files directory invalid
  • 11 - Messaging support module not found
  • 12 - Utilities module not found
  • 13 - File handling module not found
  • 14 - System files directory invalid
  • 15 - Resource definition file directory invalid
  • 16 - Region directory invalid
System Action:
Terminate the requesting process
Resolution:
Determine the cause of the error from the return-code table and re-try
Destination:
standard error
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0001 - CASCF0015


CASCF0010S

An unrecognized line was found in the global configuration file ($CASDIR/dfhtx.cfg) at the line shown.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Correct the fault with the configuration file ensuring that the line contains a valid configuration item
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0001 - CASCF0015


CASCF0011S

An unrecognized line was found in the region configuration file ($REGIONBASE/$CASREGN/dfhtx.cfg) at the line shown.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Terminate the requesting process
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0001 - CASCF0015


CASCF0012S

An unrecognized line was found in the development configuration file (dfhtxdev.cfg) at the line shown.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Correct the fault with the configuration file ensuring that the line contains a valid configuration item
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0001 - CASCF0015


CASCF0013S

The global configuration file ($CASDIR/dfhtx.cfg) could not located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure that $CASDIR is set correctly and that the configuration file exists
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0001 - CASCF0015


CASCF0014S

The region configuration file ($REGIONBASE/$CASREGN/dfhtx.cfg) could not be located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure that $CASDIR is set correctly and that the configuration file exists
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0001 - CASCF0015


CASCF0015S

The development configuration file (dfhtxdev.cfg) could not be located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure that $CASDIR is set correctly and that the configuration file exists
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0001 - CASCF0015


CASCF0016 - CASCF0030

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCF0016S
    The global configuration save file ($CASDIR/gcf.bin) could not located.
  • CASCF0017S
    The region configuration save file ($REGIONBASE/$CASREGN/rcf.bin) could not be located.
  • CASCF0018S
    The development configuration file (dcf.bin) could not be located.
  • CASCF0019S
    An error occurred when creating the global configuration save file (gcf.bin).
  • CASCF0020S
    An error occurred when creating the region configuration save file (rcf.bin).
  • CASCF0021S
    An error occurred when creating the development configuration save file (dcf.bin).
  • CASCF0022S
    An error occurred when opening the global configuration save file (gcf.bin).
  • CASCF0023S
    An error occurred when opening the region configuration save file (rcf.bin).
  • CASCF0024S
    An error occurred when opening the development configuration save file (dcf.bin).
  • CASCF0025S
    An error occurred when opening the global configuration file ($CASDIR/dfhtx.cfg)
  • CASCF0026S
    An error occurred when opening the region configuration file ($REGIONBASE/$CASREGN/dfhtx.cfg).
  • CASCF0027S
    An error occurred when opening the development configuration file (dfhtxdev.cfg).
  • CASCF0028S
    An error occurred when reading the global configuration save file (gcf.bin).
  • CASCF0029S
    An error occurred when reading the region configuration save file (rcf.bin).
  • CASCF0030S
    An error occurred when reading the development configuration save file (dcf.bin).
Parent topic: CASCF Error Messages


CASCF0016S

The global configuration save file ($CASDIR/gcf.bin) could not located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure that $CASDIR is set correctly and that the configuration file exists. If you are using $CASLOCAL make sure that it is set correctly.
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0017S

The region configuration save file ($REGIONBASE/$CASREGN/rcf.bin) could not be located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure that $CASDIR is set correctly and a multi-tasking region is running
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0018S

The development configuration file (dcf.bin) could not be located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure that $CASDIR is set correctly and that the configuration file exists
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0019S

An error occurred when creating the global configuration save file (gcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0020S

An error occurred when creating the region configuration save file (rcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0021S

An error occurred when creating the development configuration save file (dcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0022S

An error occurred when opening the global configuration save file (gcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0023S

An error occurred when opening the region configuration save file (rcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0024S

An error occurred when opening the development configuration save file (dcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0025S

An error occurred when opening the global configuration file ($CASDIR/dfhtx.cfg)
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0026S

An error occurred when opening the region configuration file ($REGIONBASE/$CASREGN/dfhtx.cfg).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0027S

An error occurred when opening the development configuration file (dfhtxdev.cfg).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0028S

An error occurred when reading the global configuration save file (gcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0029S

An error occurred when reading the region configuration save file (rcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0030S

An error occurred when reading the development configuration save file (dcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0016 - CASCF0030


CASCF0031 - CASCF0045

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCF0031S
    An error occurred when reading the global configuration file ($CASDIR/dfhtx.cfg)
  • CASCF0032S
    An error occurred when opening the region configuration file ($REGIONBASE/$CASREGN/dfhtx.cfg).
  • CASCF0033S
    An error occurred when opening the development configuration file (dfhtxdev.cfg).
  • CASCF0034S
    An error occurred when writing the global configuration save file (gcf.bin).
  • CASCF0035S
    An error occurred when writing the region configuration save file (rcf.bin).
  • CASCF0036S
    An error occurred when writing the development configuration save file (dcf.bin).
  • CASCF0037S
    The directory specified by the CASLOCAL environment variable is invalid.
  • CASCF0038S
    The directory specified by the CASDIR environment variable is invalid.
  • CASCF0039S
    The region file directory ($REGIONBASE/$CASREGN/files/reg) is invalid.
  • CASCF0040S
    The resource definition file path points to a directory is invalid.
  • CASCF0041S
    The system files directory ($CASDIR/files/sys) is invalid.
  • CASCF0042S
    The region's base directory ($REGIONBASE/$CASREGN) in invalid.
  • CASCF0043F
    The messaging support module could not be loaded as part of system initialization. This module is required for normal system operation.
  • CASCF0044F
    The utility support module could not be loaded as part of system initialization. This module is required for normal system operation.
  • CASCF0045F
    The file handling support module could not be loaded as part of system initialization. This module is required for normal system operation.
Parent topic: CASCF Error Messages


CASCF0031S

An error occurred when reading the global configuration file ($CASDIR/dfhtx.cfg)
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0032S

An error occurred when opening the region configuration file ($REGIONBASE/$CASREGN/dfhtx.cfg).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0033S

An error occurred when opening the development configuration file (dfhtxdev.cfg).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0034S

An error occurred when writing the global configuration save file (gcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0035S

An error occurred when writing the region configuration save file (rcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0036S

An error occurred when writing the development configuration save file (dcf.bin).
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check the access permissions on the drive/directory/file
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0037S

The directory specified by the CASLOCAL environment variable is invalid.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that the directory that is specified in CASLOCAL is valid and retry
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0038S

The directory specified by the CASDIR environment variable is invalid.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that the directory that is specified in CASDIR is valid and retry
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0039S

The region file directory ($REGIONBASE/$CASREGN/files/reg) is invalid.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that region name is correct and the directory exists
Destination:
Standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0040S

The resource definition file path points to a directory is invalid.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that RDTDIR item is correct and the directory exists
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0041S

The system files directory ($CASDIR/files/sys) is invalid.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that CASDIR is correct and the directory exists
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0042S

The region's base directory ($REGIONBASE/$CASREGN) in invalid.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that region name is correct and the directory exists
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0043F

The messaging support module could not be loaded as part of system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that $CASDIR is set correctly and the module dfh0msg exists in $CASDIR/lib.
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0044F

The utility support module could not be loaded as part of system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that $CASDIR is set correctly and the module(s) dfh0utl exists in $CASDIR/lib
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0045F

The file handling support module could not be loaded as part of system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that $CASDIR is set correctly and the module dfhextfh exists in $CASDIR/lib
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0031 - CASCF0045


CASCF0046 - CASCF0064

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCF0046F
    The file handling support module could not be loaded as part of system initialization. This module is required for normal system operation.
  • CASCF0047F
    An unexpected error occurred in system initialization while processing the configuration file.
  • CASCF0048F
    The value for the environment variable is larger than the internal work areas. This may result in an invalid value so the initialization will be aborted.
  • CASCF0049F
    The activation key for the product is invalid or has expired.
  • CASCF0050S
    An error occurred accessing the console daemon configuration data. Typically this occurs when the console daemon is not currently active.
  • CASCF0051S
    An error occurred accessing the region configuration data. Typically this occurs when the region is not currently active.
  • CASCF0052S
    An error occurred reading the console daemon's stored configuration data. This may occur if the console daemon failed in initialization or the registry data has become corrupted.
  • CASCF0053S
    An error occurred reading the region's stored configuration data. This may occur if the region failed in initialization or the registry data has become corrupted.
  • CASCF0054S
    An error occurred writing the console daemons stored configuration data. This may occur if the registry data has become corrupted.
  • CASCF0055S
    An error occurred writing the region's stored configuration data. This may occur if the registry data has become corrupted.
  • CASCF0056S
    An error occurred reading the project's configuration data. This may occur if this process was not invoked by the IDE or no project is open. Check that the appropriate configuration value is set within the current project or workgroup settings.
  • CASCF0057S
    An error occurred reading the project's configuration data. This may occur if this process was not invoked by the IDE or no project is open. Check that the appropriate configuration value is set within the current project or workgroup settings.
  • CASCF0058S
    An error occurred reading the project's configuration data. This may occur if this process was not invoked by the IDE or no project is open. Check that the appropriate configuration value is set within the current project or workgroup settings.
  • CASCF0059F
    The CAS configuration module could not be located during system initialization. This module is required for normal system operation.
  • CASCF0061F
    The system groups have not been defined in $COBDIR/etc/cas/dfhtx.cfg
  • CASCF0062F
    The module has not been recognized by the authorisation process
  • CASCF0063F
    The group associated with the module has not been recognized
  • CASCF0064W config-module: Region region-name has already been stopped
    An error occurred accessing the regions shared memory. Typically this occurs when the region is not currently active.
Parent topic: CASCF Error Messages


CASCF0046F

The file handling support module could not be loaded as part of system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Check that $CASDIR is set correctly and the module mffh exists in $COBDIR
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0047F

An unexpected error occurred in system initialization while processing the configuration file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Some values for RC are:

  • 01 - No region name specified
  • 02 - Bad line in file
  • 03 - File not found
  • 04 - Error creating file
  • 05 - Error opening file
  • 06 - Error reading file
  • 07 - Error writing to file
  • 08 - CASLOCAL invalid
  • 09 - CASDIR invalid
  • 10 - Region files directory invalid
  • 11 - Messaging support module not found
  • 12 - Utilities module not found
  • 13 - File handling module not found
  • 14 - System files directory invalid
  • 15 - Resource definition file directory invalid
  • 16 - Region directory invalid
  • 17 - Environment variable too large
System Action:
Terminate the requesting process
Resolution:
Determine the cause of the error from the return-code table and re-try
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0048F

The value for the environment variable is larger than the internal work areas. This may result in an invalid value so the initialization will be aborted.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Some values for ID are:

  • 01 - $COBCPY / CASCPYSRC
System Action:
Terminate the requesting process
Resolution:
Check the directories specified in the appropriate environment variable / configuration items are required
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0049F

The activation key for the product is invalid or has expired.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Contact your Micro Focus representative
Destination:
standard error
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0046 - CASCF0064


CASCF0050S

An error occurred accessing the console daemon configuration data. Typically this occurs when the console daemon is not currently active.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure the console daemon is active and retry
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0051S

An error occurred accessing the region configuration data. Typically this occurs when the region is not currently active.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure the region is active and retry
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0052S

An error occurred reading the console daemon's stored configuration data. This may occur if the console daemon failed in initialization or the registry data has become corrupted.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure that the console daemon is active and retry
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0053S

An error occurred reading the region's stored configuration data. This may occur if the region failed in initialization or the registry data has become corrupted.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure that the region is active and retry
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0054S

An error occurred writing the console daemons stored configuration data. This may occur if the registry data has become corrupted.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0055S

An error occurred writing the region's stored configuration data. This may occur if the registry data has become corrupted.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0056S

An error occurred reading the project's configuration data. This may occur if this process was not invoked by the IDE or no project is open. Check that the appropriate configuration value is set within the current project or workgroup settings.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure the IDE is active and a valid project file is open
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0057S

An error occurred reading the project's configuration data. This may occur if this process was not invoked by the IDE or no project is open. Check that the appropriate configuration value is set within the current project or workgroup settings.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure the IDE is active and a valid project file is open
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0058S

An error occurred reading the project's configuration data. This may occur if this process was not invoked by the IDE or no project is open. Check that the appropriate configuration value is set within the current project or workgroup settings.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Make sure the IDE is active and a valid project file is open
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0059F

The CAS configuration module could not be located during system initialization. This module is required for normal system operation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Destination:
standard error
Module:
config-module(dfhcpcfe)
Parent topic: CASCF0046 - CASCF0064


CASCF0061F

The system groups have not been defined in $COBDIR/etc/cas/dfhtx.cfg
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Ensure that dfhtx.cfg contains entries for system groups
Destination:
standard error
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0046 - CASCF0064


CASCF0062F

The module has not been recognized by the authorisation process
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
>Terminate the requesting process
Resolution:
Contact Micro Focus
Destination:
standard error
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0046 - CASCF0064


CASCF0063F

The group associated with the module has not been recognized
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process
Resolution:
Contact system administrator. Group owner not declared in groups
Destination:
Standard error
Module:
config-module(dfhcpcfi)
Parent topic: CASCF0046 - CASCF0064


CASCF0064W config-module: Region region-name has already been stopped

An error occurred accessing the regions shared memory. Typically this occurs when the region is not currently active.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Terminate the requesting process.
Resolution:
Make sure the region is active and retry.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0046 - CASCF0064


CASCL Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASCL0000 - CASCL0012
  • CASCL0020 - CASCL0027
Parent topic: Enterprise Server Error Messages


CASCL0000 - CASCL0012

  • CASCL0000S Auto-install error, NETNAME netname busy
    During the auto-install process the requested or generated netname was already ENQed by another process.
  • CASCL0001S Auto-install error, ENQ on NETNAME netname error
    During the auto-install process the requested or generated netname could not be ENQed.
  • CASCL0002S Auto-install error, NETNAME netname already in use
    During the auto-install process the requested or generated netname was already being used.
  • CASCL0003S Auto-install error, TERMTYPE termtype locate error
    During the auto-install process the termtype entry referenced could not be located.
  • CASCL0004S Auto-install rejected by user exit
    During the auto-install process the user exit rejected the Transaction System client's connection.
  • CASCL0005 Auto-install error, TCT rechain error = tmp-return
    During the auto-install process the TCT entry could not be installed to the system.
  • CASCL0006S Auto-install error, netname delete error = tmp-return
    During the auto-install process the tcts entry could not be deleted.
  • CASCL0007S Auto-install, error calling user exit
    During the auto-install process an error occurred linking to the user exit specified in the SIT.
  • CASCL0008S Auto-install error, MODEL model locate error
    During the auto-install process the model selected by the user exit could not be located.
  • CASCL0009S Auto-install error, NETNAME netname out of service
    During the auto-install process the tcts selected was marked as out of service.
  • CASCL0010S Auto-install error, NETNAME netname definition not client type
    During the auto-install process the tcts selected was not a client tcts.
  • CASCL0011S Auto-install error, NETNAME netname TCTUA allocation failure
    During the auto-install process the tcts selected requested a shared storage TCTUA. There was a failure when attempting to allocate it.
  • CASCL0012S Auto-install error: Error calling exit "exit-name"
    During the auto-install process the user-specified auto-install exit could not be called.
Parent topic: CASCL Error Messages


CASCL0000S Auto-install error, NETNAME netname busy

During the auto-install process the requested or generated netname was already ENQed by another process.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0001S Auto-install error, ENQ on NETNAME netname error

During the auto-install process the requested or generated netname could not be ENQed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0002S Auto-install error, NETNAME netname already in use

During the auto-install process the requested or generated netname was already being used.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0003S Auto-install error, TERMTYPE termtype locate error

During the auto-install process the termtype entry referenced could not be located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0004S Auto-install rejected by user exit

During the auto-install process the user exit rejected the Transaction System client's connection.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0005 Auto-install error, TCT rechain error = tmp-return

During the auto-install process the TCT entry could not be installed to the system.

Some values for tmp-return are:

1
not found
1
not found
2
busy
3
invalid request
6
duplicate termid
9
tctid invalid
10
duplicate netname
11
netname invalid
12
duplicate plu alias
13
plu alias invalid
20
out of service
21
not acquired
22
invalid type
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0006S Auto-install error, netname delete error = tmp-return

During the auto-install process the tcts entry could not be deleted.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Try starting the Transaction System client with another netname.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0007S Auto-install, error calling user exit

During the auto-install process an error occurred linking to the user exit specified in the SIT.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the name of the user auto-install exit is correct and the program is located on the search path.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0008S Auto-install error, MODEL model locate error

During the auto-install process the model selected by the user exit could not be located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the user exit is working correctly.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0009S Auto-install error, NETNAME netname out of service

During the auto-install process the tcts selected was marked as out of service.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the user exit is working correctly.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0010S Auto-install error, NETNAME netname definition not client type

During the auto-install process the tcts selected was not a client tcts.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the terminal definition is correct.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0011S Auto-install error, NETNAME netname TCTUA allocation failure

During the auto-install process the tcts selected requested a shared storage TCTUA. There was a failure when attempting to allocate it.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that enough shared pages are defined.
Module:
dfhzai
Destination:
TDQ CAIL and Transaction System client
Parent topic: CASCL0000 - CASCL0012


CASCL0012S Auto-install error: Error calling exit "exit-name"

During the auto-install process the user-specified auto-install exit could not be called.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected.
Resolution:
Make sure that the exit named specified is correct and the exit is available on the search path.
Module:
dfhzai
Destination:
TDQ CAIL and console
Parent topic: CASCL0000 - CASCL0012


CASCL0020 - CASCL0027

  • CASCL0020I Printer term-id initialized successfully
    The 3270 printer daemon has successfully initialized the emulation of the printer with termid specified.
  • CASCL0021I Printer term-id disconnected successfully
    The 3270 printer daemon has disconnected successfully.
  • CASCL0022W Printer auto-install failure, RC: terminal-id
    An error occurred in the auto-install of printer .
  • CASCL0023W Printer registration failure, return code = return-code
    An error occurred in the registration of a printer.
  • CASCL0024S Printer memory allocation failure, return code = malloc-return-code
    An error occurred in the initialization of a printer. The memory allocation failed for the printers control areas.
  • CASCL0025I Terminal disconnected successfully
    The 3270 terminal has disconnected successfully.
  • CASCL0026S Auto-install error, hash table processing, NETNAME = netname
    Hash table processing for the specified NETNAME failed.
  • CASCL0027E Auto-install error, LU1 NETNAME(netname) MODEL(), device does not support SCS
    The device does not report SCS support but the selcected terminal model requires SCS support.
Parent topic: CASCL Error Messages


CASCL0020I Printer term-id initialized successfully

The 3270 printer daemon has successfully initialized the emulation of the printer with termid specified.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The printer is now available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0027


CASCL0021I Printer term-id disconnected successfully

The 3270 printer daemon has disconnected successfully.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The printer is no longer available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0027


CASCL0022W Printer auto-install failure, RC: terminal-id

An error occurred in the auto-install of printer .
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The printer will not be available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0027


CASCL0023W Printer registration failure, return code = return-code

An error occurred in the registration of a printer.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The printer will not be available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0027


CASCL0024S Printer memory allocation failure, return code = malloc-return-code

An error occurred in the initialization of a printer. The memory allocation failed for the printers control areas.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The printer will not be available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0027


CASCL0025I Terminal disconnected successfully

The 3270 terminal has disconnected successfully.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhzexit
Destination:
Standard error
Parent topic: CASCL0020 - CASCL0027


CASCL0026S Auto-install error, hash table processing, NETNAME = netname

Hash table processing for the specified NETNAME failed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The auto-install is rejected system dump generated.
Resolution:
Report error to Micro Focus Technical Support supplying generated dump file.
Module:
dfhzai
Destination:
Console Standard error
Parent topic: CASCL0020 - CASCL0027


CASCL0027E Auto-install error, LU1 NETNAME(netname) MODEL(), device does not support SCS

The device does not report SCS support but the selcected terminal model requires SCS support.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The client is rejected.
Resolution:
Correct the terminal model or the client configuration and retry.
Module:
dfhzai
Destination:
Console Standard error
Parent topic: CASCL0020 - CASCL0027


CASDB Error Messages

  • CASDB5001I IMS DB Control Process initialization started
    The server IMS DB Control Process initialization has started.
  • CASDB5002S IMS DB Control Process is not running in multi-threaded mode
    The IMS DB Control Process has not started with the required underlying thread support.
  • CASDB5003I IMS DB Control Process initialization complete
    The IMS DB Control Process has completed initialization.
  • CASDB5004S IMS DB Control Process registration failed, reason = reason-code
    The IMS DB Control Process failed registration. The reason code is reason-code.
  • CASDB5005S IMS DB Control Process storage allocation error
    The IMS DB Control Process experienced a problem allocating control blocks in local storage.
  • CASDB5006I ims-control-message
    The IMS DB Control Process issued a message. The text is ims-control-message.
  • CASDB5007I IMS DB Control Process termination started
    The IMS DB Control Process is terminating.
  • CASDB5008I IMS DB Control Process termination complete
    The IMS DB Control Process has terminated.
  • CASDB5011I IMS DB Control Process restart in progress
    The IMS TM Control process has been restarted and recovery operations are in progress.
  • CASDB5059I IMS DB process generated a dump to dump dataset dump-dataset
    A dump of the IMS DB process was requested and this dump was generated to the dump-dataset dump dataset.
  • CASDB5060S IMS DB Control Process DLI engine failed to initialize, reason = reason-code
    The IMS DB Control Process failed to initialize the core DLI engine. The reason code is reason-code.
Parent topic: Enterprise Server Error Messages


CASDB5001I IMS DB Control Process initialization started

The server IMS DB Control Process initialization has started.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5002S IMS DB Control Process is not running in multi-threaded mode

The IMS DB Control Process has not started with the required underlying thread support.
System Action:
The IMS DB Control Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5003I IMS DB Control Process initialization complete

The IMS DB Control Process has completed initialization.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5004S IMS DB Control Process registration failed, reason = reason-code

The IMS DB Control Process failed registration. The reason code is reason-code.
System Action:
The IMS DB Control Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5005S IMS DB Control Process storage allocation error

The IMS DB Control Process experienced a problem allocating control blocks in local storage.
System Action:
The IMS DB Control Process is terminated.
Resolution:
Notify Micro Focus Support.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5006I ims-control-message

The IMS DB Control Process issued a message. The text is ims-control-message.
System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5007I IMS DB Control Process termination started

The IMS DB Control Process is terminating.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5008I IMS DB Control Process termination complete

The IMS DB Control Process has terminated.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5011I IMS DB Control Process restart in progress

The IMS TM Control process has been restarted and recovery operations are in progress.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5059I IMS DB process generated a dump to dump dataset dump-dataset

A dump of the IMS DB process was requested and this dump was generated to the dump-dataset dump dataset.
System Action:
The IMS DB process produceses a dump.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDB5060S IMS DB Control Process DLI engine failed to initialize, reason = reason-code

The IMS DB Control Process failed to initialize the core DLI engine. The reason code is reason-code.
System Action:
The IMS DB Control Process is terminated and DLI functionality is not availabel.
Resolution:
Check the message issued by the DLI engine and the reason code.
Module:
casdbc
Destination:
Console
Parent topic: CASDB Error Messages


CASDU Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASDU0001W Error return-code deleting dump/trace file dump-filename
    An error occurred trying to delete the dump/trace file on region cold start.
  • CASDU0002W Error return-code deleting dump/trace file dump-filename
    An error occurred trying to delete the dump/trace file on region cold start.
  • CASDU0003W Error return-code deleting diagnostic file diagnostic-filename
    An error occurred trying to delete the dump/trace file on region cold start.
  • CASDU0004I Switched diagnostic output to diagnostic-filename
    An error occurred trying to delete the dump/trace file on region cold start.
  • CASDU0005I AUX Trace stopped and flushed to diagnostic-filename
    An error occurred trying to delete the dump/trace file on region cold start.
Parent topic: Enterprise Server Error Messages


CASDU0001W Error return-code deleting dump/trace file dump-filename

An error occurred trying to delete the dump/trace file on region cold start.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
dfhginit
Destination:
Console and standard error
Parent topic: CASDU Error Messages


CASDU0002W Error return-code deleting dump/trace file dump-filename

An error occurred trying to delete the dump/trace file on region cold start.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASDU Error Messages


CASDU0003W Error return-code deleting diagnostic file diagnostic-filename

An error occurred trying to delete the dump/trace file on region cold start.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
casrdo11
Destination:
Console and standard error
Parent topic: CASDU Error Messages


CASDU0004I Switched diagnostic output to diagnostic-filename

An error occurred trying to delete the dump/trace file on region cold start.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
casrdo11
Destination:
Console and standard error
Parent topic: CASDU Error Messages


CASDU0005I AUX Trace stopped and flushed to diagnostic-filename

An error occurred trying to delete the dump/trace file on region cold start.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The system will ignore the error and continue.
Resolution:
Check the return-code for CBL_DELETE_FILE and fix the reported problem if required.
Module:
casrdo11
Destination:
Console and standard error
Parent topic: CASDU Error Messages


CASFC Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASFC0001I Fileshare services initialized
    The Fileshare facility is initialized and ready to accept requests.
  • CASFC0002I Fileshare terminated
    The Fileshare facility has terminated normally.
  • CASFC0003S Fileshare initialization terminated abnormally
    The Fileshare facility terminated during initialization.
  • CASFC0004S Critical Fileshare storage error
    The Fileshare facility encountered a local storage failure that was not recoverable.
  • CASFC0005I Fileshare services message fileshare-message
    This message in standard Fileshare format.
  • CASFC0006I Fileshare current directory set to current-directory
    The effective current directory for Fileshare function is set to current-directory.
  • CASFC0007I Fileshare services recovery initiated
    The intigrated Fileshare program has been restarted after a failure and the new process is recovering pending requests.
  • CASFC0008I Error accessing file () group () - status=(,). File marked as closed and disabled.
    An error occured while accessing the file. I/O is error specified in file-status. If file-status-1 is 3 then the error is a standard file status code. A file-status-2 of 9 indicates a RTS error. The file has been marked as closed and disabled.
  • CASFC0009I User (user-id) requested (request type) on file (filename) group (file group name) from Tran (trans-id) Program (terminal-id) Terminal ().
    Logging username, filename and all open,close,enable and disable requests on a CICS files.
Parent topic: Enterprise Server Error Messages


CASFC0001I Fileshare services initialized

The Fileshare facility is initialized and ready to accept requests.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhgfshr
Destination:
Console and standard error.
Parent topic: CASFC Error Messages


CASFC0002I Fileshare terminated

The Fileshare facility has terminated normally.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhgfshr
Destination:
Console and standard error.
Parent topic: CASFC Error Messages


CASFC0003S Fileshare initialization terminated abnormally

The Fileshare facility terminated during initialization.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The process is terminated. File services are not available to the region.
Resolution:
Correct the error and restart the region.
Module:
dfhgfshr
Destination:
Console and standard error.
Parent topic: CASFC Error Messages


CASFC0004S Critical Fileshare storage error

The Fileshare facility encountered a local storage failure that was not recoverable.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region is terminated abnormally.
Resolution:
Correct the error and restart the region.
Module:
dfhgfshr
Destination:
Console and standard error.
Parent topic: CASFC Error Messages


CASFC0005I Fileshare services message fileshare-message

This message in standard Fileshare format.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Resolution:
Consult separate Fileshare message documentation.
Module:
dfhgfshr
Destination:
Console and standard error.
Parent topic: CASFC Error Messages


CASFC0006I Fileshare current directory set to current-directory

The effective current directory for Fileshare function is set to current-directory.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhgfshr
Destination:
Console and standard error.
Parent topic: CASFC Error Messages


CASFC0007I Fileshare services recovery initiated

The intigrated Fileshare program has been restarted after a failure and the new process is recovering pending requests.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhgfshr
Destination:
Console and standard error.
Parent topic: CASFC Error Messages


CASFC0008I Error accessing file () group () - status=(,). File marked as closed and disabled.

An error occured while accessing the file. I/O is error specified in file-status. If file-status-1 is 3 then the error is a standard file status code. A file-status-2 of 9 indicates a RTS error. The file has been marked as closed and disabled.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Resolution:
Check the file.
Module:
dfhefctl
Destination:
Console
Parent topic: CASFC Error Messages


CASFC0009I User (user-id) requested (request type) on file (filename) group (file group name) from Tran (trans-id) Program (terminal-id) Terminal ().

Logging username, filename and all open,close,enable and disable requests on a CICS files.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhesysp
Destination:
CSFL
Parent topic: CASFC Error Messages


CASFD Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASFD0001 - CASFD0014
Parent topic: Enterprise Server Error Messages


CASFD0001 - CASFD0014

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASFD0001I
    The offline dump requester issued a dump request for region region-name. The dump went to the normal region dump dataset.
  • CASFD0002S
    The offline dump requester failed in its attempt to contact the region.
  • CASFD0003S
    The offline dump requester failed in its attempt to change to the region's directories.
  • CASFD0004S
    The offline dump requester failed in its attempt to change to the root Transaction System directory.
  • CASFD0005S
    The offline dump requester failed in its attempt to change to the region's directories.
  • CASFD0006S
    The offline dump requester failed in its attempt to set environment variables.
  • CASFD0007S
    The offline dump requester failed to find the requester support module.
  • CASFD0010I
    The offline dump/trace format request is complete.
  • CASFD0011I
    The output from the offline dump/trace format request was written to the output file output-file-name.
  • CASFD0012E
    No input dump/trace dataset could be located.
  • CASFD0014E
    The input Dump/Trace dataset was not generated on the same bitism environment.
Parent topic: CASFD Error Messages


CASFD0001I

The offline dump requester issued a dump request for region region-name. The dump went to the normal region dump dataset.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The dump request is issued
Resolution:
None.
Destination:
Console and standard error.
Module:
dfhgtrtd
Parent topic: CASFD0001 - CASFD0014


CASFD0002S

The offline dump requester failed in its attempt to contact the region.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The dump request is ignored
Resolution:
Check that the region is active.
Destination:
Console and standard error.
Module:
dfhgtrtd
Parent topic: CASFD0001 - CASFD0014


CASFD0003S

The offline dump requester failed in its attempt to change to the region's directories.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The dump request is ignored
Resolution:
Correct the region specification and retry the operation.
Destination:
Console and standard error.
Module:
dfhgtrtd
Parent topic: CASFD0001 - CASFD0014


CASFD0004S

The offline dump requester failed in its attempt to change to the root Transaction System directory.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The dump request is ignored
Resolution:
Correct the CASDIR specification and retry the operation.
Destination:
Console and standard error.
Module:
dfhgtrtd
Parent topic: CASFD0001 - CASFD0014


CASFD0005S

The offline dump requester failed in its attempt to change to the region's directories.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The dump request is ignored
Resolution:
Correct the region specification and retry the operation.
Destination:
Console and standard error.
Module:
dfhgtrtd
Parent topic: CASFD0001 - CASFD0014


CASFD0006S

The offline dump requester failed in its attempt to set environment variables.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The dump request is ignored
Resolution:
Correct the configuration specification and retry the operation.
Destination:
Console and standard error.
Module:
dfhgtrtd
Parent topic: CASFD0001 - CASFD0014


CASFD0007S

The offline dump requester failed to find the requester support module.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The dump request is aborted
Resolution:
Correct the installation setup and retry the operation.
Destination:
Console and standard error.
Module:
dfhgtrtd
Parent topic: CASFD0001 - CASFD0014


CASFD0010I

The offline dump/trace format request is complete.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
None
Resolution:
None
Destination:
Standard error.
Module:
dfhgdup
Parent topic: CASFD0001 - CASFD0014


CASFD0011I

The output from the offline dump/trace format request was written to the output file output-file-name.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
None
Resolution:
None
Destination:
Standard error.
Module:
dfhgdup
Parent topic: CASFD0001 - CASFD0014


CASFD0012E

No input dump/trace dataset could be located.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
None
Resolution:
Check the location of the dump/trace datasets and retry. Dump/Trace dataset names:
Destination:
Standard error.
Module:
dfhgdup
Parent topic: CASFD0001 - CASFD0014


CASFD0014E

The input Dump/Trace dataset was not generated on the same bitism environment.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
None
Resolution:
Check your current environment.
Destination:
Standard error.
Module:
dfhgdup
Parent topic: CASFD0001 - CASFD0014


CASFF Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASFF0001I Searching 'Search-path' for the location of 'file-name'
    The file 'Search-path' is being searched for using the system search path 'file-name'.
  • CASFF0002I Searching for the location of 'file-name'
    The file 'file-name' is being searched for.
  • CASFF0003I 'file-name' was found file-name-path
    The file 'file-name' was found on the system search path 'file-name'.
  • CASFF0004I Searched 'Search-path' path and failed to find 'file-name'
    The file 'file-name' was not found on the system search path 'file-name'.
  • CASFF0005I Failed to find 'file-name'
    The file 'file-name' was not found on the search path.
  • CASFF0006S Invalid parameter on command line : command-line
    The command line parameter command-line is in valid.
Parent topic: Enterprise Server Error Messages


CASFF0001I Searching 'Search-path' for the location of 'file-name'

The file 'Search-path' is being searched for using the system search path 'file-name'.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF Error Messages


CASFF0002I Searching for the location of 'file-name'

The file 'file-name' is being searched for.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF Error Messages


CASFF0003I 'file-name' was found file-name-path

The file 'file-name' was found on the system search path 'file-name'.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF Error Messages


CASFF0004I Searched 'Search-path' path and failed to find 'file-name'

The file 'file-name' was not found on the system search path 'file-name'.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF Error Messages


CASFF0005I Failed to find 'file-name'

The file 'file-name' was not found on the search path.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF Error Messages


CASFF0006S Invalid parameter on command line : command-line

The command line parameter command-line is in valid.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF Error Messages


CASRM Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASRM0001I ODBC resource manager initialized
    The ODBC resource manager is initialized and ready to accept requests.
  • CASRM0002S ODBC resource manager initialization terminated abnormally, RC=return-code
    The ODBC resource manager terminated during initialization.
  • CASRM0003I ODBC resource manager terminated
    The ODBC resource manager facility has terminated normally.
  • CASRM0004W ODBC resource manager warning warning-message
    The ODBC resource manager encountered a recoverable error.
  • CASRM0005S ODBC resource manager error error-message
    The ODBC resource manager encountered an unrecoverable error.
Parent topic: Enterprise Server Error Messages


CASRM0001I ODBC resource manager initialized

The ODBC resource manager is initialized and ready to accept requests.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM Error Messages


CASRM0002S ODBC resource manager initialization terminated abnormally, RC=return-code

The ODBC resource manager terminated during initialization.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The process is terminated. ODBC services are not available to the region.
Resolution:
Correct the error and restart the region.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM Error Messages


CASRM0003I ODBC resource manager terminated

The ODBC resource manager facility has terminated normally.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM Error Messages


CASRM0004W ODBC resource manager warning warning-message

The ODBC resource manager encountered a recoverable error.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Processing will continue normally.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM Error Messages


CASRM0005S ODBC resource manager error error-message

The ODBC resource manager encountered an unrecoverable error.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The ODBC resource manager will terminate abnormally.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM Error Messages


CASSP Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASSP0001 - CASSP0014
Parent topic: Enterprise Server Error Messages


CASSP0001 - CASSP0014

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASSP0001W
    The console daemon detected a process's termination and attempted to inform the region manger of the event. It failed due to the reason given.
  • CASSP0002I
    The console daemon detected a process's termination and successfully informed the region manger of the event. pinfo describes the process information details
  • CASSP0003E
    The daemon process responsible for initiating recovery for process-id failed trying to lock shared memory.
  • CASSP0004E
    The daemon process responsible for initiating recovery for process ID process-id failed trying to lock shared memory.
  • CASSP0010S
    A syncpoint, either implied or requested via API has failed and the DB/file resource state is unpredictable.
  • CASSP0011S
    A syncpoint was requested and attempted against the configured resource managers. A bad response was returned and the resource managers were rolledback to the previous syncpoint.
  • CASSP0013S
    A rollback, either implied or requested via API has failed and the DB/file resource state is unpredictable.
  • CASSP0014S
    The process terminated due to a COBOL RTS error.
Parent topic: CASSP Error Messages


CASSP0001W

The console daemon detected a process's termination and attempted to inform the region manger of the event. It failed due to the reason given.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region manager cannot be informed of the process's termination. The region may continue successfully. If the reason is 3 then this may be normal if the region is in the process of shutting down.
Resolution:
None
Destination:
Console
Module:
caspdied
Parent topic: CASSP0001 - CASSP0014


CASSP0002I

The console daemon detected a process's termination and successfully informed the region manger of the event. pinfo describes the process information details
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region manager will take appropriate action to recover after the process's termination
Resolution:
None
Destination:
Console
Module:
caspdied
Parent topic: CASSP0001 - CASSP0014


CASSP0003E

The daemon process responsible for initiating recovery for process-id failed trying to lock shared memory.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region manager cannot be informed of the process's termination. The region may continue successfully.
Resolution:
None
Destination:
Console
Module:
dfhgdied
Parent topic: CASSP0001 - CASSP0014


CASSP0004E

The daemon process responsible for initiating recovery for process ID process-id failed trying to lock shared memory.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region manager cannot be informed of the process's termination. The region may continue successfully.
Resolution:
None
Destination:
Console
Module:
dfhgdied
Parent topic: CASSP0001 - CASSP0014


CASSP0010S

A syncpoint, either implied or requested via API has failed and the DB/file resource state is unpredictable.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The transaction will abend.
Resolution:
Investigate why the syncpoint failed and restore the database resource managers to a known position.
Destination:
Console and standard error.
Module:
dfhesync
Parent topic: CASSP0001 - CASSP0014


CASSP0011S

A syncpoint was requested and attempted against the configured resource managers. A bad response was returned and the resource managers were rolledback to the previous syncpoint.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The transaction will abend.
Resolution:
Investigate why the syncpoint failed.
Destination:
Console and standard error.
Module:
dfhesync
Parent topic: CASSP0001 - CASSP0014


CASSP0013S

A rollback, either implied or requested via API has failed and the DB/file resource state is unpredictable.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The transaction will abend.
Resolution:
Investigate why the rollback failed and restore the database resource managers to a known position.
Destination:
Console and standard error.
Module:
dfhesync
Parent topic: CASSP0001 - CASSP0014


CASSP0014S

The process terminated due to a COBOL RTS error.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Depending on the process type the system will restart the process.
Resolution:
None
Destination:
Console and standard error.
Module:
cascperr
Parent topic: CASSP0001 - CASSP0014


CASST Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASST0000 - CASST0020
  • CASST4000 - CASST4111
  • CASST5000 - CASST6002
Parent topic: Enterprise Server Error Messages


CASST0000 - CASST0020

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASST0000I
    The region manager has started its termination phase
  • CASST0001I
    The region manager has completed its termination phase
  • CASST0002W
    While attempting to shutdown a region an error occurred trying to attach to the region.
  • CASST0003W
    An attempt was made to shutdown a region externally which is marked as having external shutdown disabled
  • CASST0004W
    An attempt was made to shutdown a region externally which is marked as requiring a valid userid and password to complete the shutdown request due to the reason given.
  • CASST0005I
    The shutdown program is starting to shutdown the region.
  • CASST0006I
    The shutdown program is starting to shutdown the region by scheduling the transaction specified.
  • CASST0007I
    The shutdown program is starting to shutdown the region by abending all region processes.
  • CASST0008W
    An attempt to shutdown a region externally via a transid was rejected as the user failed the security check on the transaction.
  • CASST0009W
    An attempt to shutdown a region externally via a transid was rejected as the transaction is defined as remote.
  • CASST0010W
    An attempt to shutdown a region externally via a transid was rejected as the transaction was not found.
  • CASST0011W
    An attempt to shutdown a region externally via a transid was rejected as the transaction could not be scheduled due to an error allocating shared memory.
  • CASST0012W
    A forceable region abend was requested via the dfhgrtrm utility. Data may be lost or the system may be left in an unstable state. This option should only be used as a last resort, it is recommended that the region is shutdown cleanly via the /t option.
  • CASST0013W
    A forceable region abend was requested via the dfhgrtrm utility without the protection of locking shared memory. This should only be used if the region is 'hung', that is, it is impossible to connect a 3270 terminal to the region or shut the region down with the /t option.
  • CASST0014E
    While attempting to shutdown a region an error occurred trying to submit the shutdown request
  • CASST0015E
    While attempting to shutdown a region an error occurred trying to submit the shutdown request
  • CASST0016E
    While attempting to shutdown a region an error occurred trying to submit the shutdown request
  • CASST0017E
    While attempting to shutdown a region with option force the request has been rejected because the region security is on
  • CASST0018S
    The Casstop process failed to initialize safmgr. The reason code is reason-code.
  • CASST0019S
    The Safmgr failed to initialize and, therefore, Enterprise Server will be shutdown.
  • CASST0020I
    The shutdown is in progress, use force if the region did not stop in a timely fashion.
Parent topic: CASST Error Messages


CASST0000I

The region manager has started its termination phase
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Shared memory and semaphores will be removed
Resolution:
None
Destination:
console
Module:
dfhgterm
Parent topic: CASST0000 - CASST0020


CASST0001I

The region manager has completed its termination phase
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
All shared memory and semaphores were removed successfully
Resolution:
None
Destination:
console
Module:
dfhgterm
Parent topic: CASST0000 - CASST0020


CASST0002W

While attempting to shutdown a region an error occurred trying to attach to the region.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
As the shut down program cannot attach to the region the region cannot be shutdown
Resolution:
Make sure that the region being shutdown is running and retry
Destination:
console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0003W

An attempt was made to shutdown a region externally which is marked as having external shutdown disabled
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will continue running
Resolution:
To shut the region down log on the region and enter the transid required to shutdown the region
Destination:
console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0004W

An attempt was made to shutdown a region externally which is marked as requiring a valid userid and password to complete the shutdown request due to the reason given.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • 1 - error opening region resource definition file
  • 2 - user did not have valid security key
  • 3 - userid and/or password invalid
System Action:
The region will continue running
Resolution:
Specify a valid userid+password on the command line. If the userid+password is valid make sure that the security keys of the user matches the external security key specified in the SIT.
Destination:
console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0005I

The shutdown program is starting to shutdown the region.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Start shutting down the region
Resolution:
None
Destination:
console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0006I

The shutdown program is starting to shutdown the region by scheduling the transaction specified.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Schedule transaction
Resolution:
None
Destination:
console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0007I

The shutdown program is starting to shutdown the region by abending all region processes.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
All region process with be abnormally ended
Resolution:
None
Destination:
console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0008W

An attempt to shutdown a region externally via a transid was rejected as the user failed the security check on the transaction.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will not be shutdown
Resolution:
Make sure that the userid and password being specified has the correct security keys set in the SNT to run the shutdown transaction
Destination:
console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0009W

An attempt to shutdown a region externally via a transid was rejected as the transaction is defined as remote.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region will not be shutdown.
Resolution:
Make sure that the transaction is local.
Destination:
Console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0010W

An attempt to shutdown a region externally via a transid was rejected as the transaction was not found.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region will not be shutdown.
Resolution:
Make sure that the transaction is in the correct case and has been installed to the region.
Destination:
Console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0011W

An attempt to shutdown a region externally via a transid was rejected as the transaction could not be scheduled due to an error allocating shared memory.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region will not be shutdown.
Resolution:
If there is no shared memory available try to shutdown the region without a transid.
Destination:
Console
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0012W

A forceable region abend was requested via the dfhgrtrm utility. Data may be lost or the system may be left in an unstable state. This option should only be used as a last resort, it is recommended that the region is shutdown cleanly via the /t option.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region will be forceably abended.
Resolution:
If a clean shutdown is required use the /t command line option on future invocations.
Destination:
Console and stdout
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0013W

A forceable region abend was requested via the dfhgrtrm utility without the protection of locking shared memory. This should only be used if the region is 'hung', that is, it is impossible to connect a 3270 terminal to the region or shut the region down with the /t option.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region will be forceably abended without first obtaining a lock on shared memory.
Resolution:
This may be the only option in severe system failures, report the failure mode to Technical Support.
Destination:
Console and stdout
Module:
dfhgrtrm
Parent topic: CASST0000 - CASST0020


CASST0014E

While attempting to shutdown a region an error occurred trying to submit the shutdown request
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
As the shut down program cannot attach to the region the region cannot be shutdown.
Resolution:
A forced region shutdown may be required.
Destination:
Console
Module:
casstop
Parent topic: CASST0000 - CASST0020


CASST0015E

While attempting to shutdown a region an error occurred trying to submit the shutdown request
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
As the shut down program cannot attach to the region the region cannot be shutdown.
Resolution:
A forced region shutdown may be required.
Destination:
Console
Module:
casstop
Parent topic: CASST0000 - CASST0020


CASST0016E

While attempting to shutdown a region an error occurred trying to submit the shutdown request
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
As the shut down program cannot attach to the region the region cannot be shutdown.
Resolution:
A forced region shutdown may be required.
Destination:
Console
Module:
casstop
Parent topic: CASST0000 - CASST0020


CASST0017E

While attempting to shutdown a region with option force the request has been rejected because the region security is on
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The region cannot be shutdown.
Resolution:
Use other system OS tools for terminating the region
Destination:
Console
Module:
casstop
Parent topic: CASST0000 - CASST0020


CASST0018S

The Casstop process failed to initialize safmgr. The reason code is reason-code.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The Casstop command is terminated.
Resolution:
Report failure to Micro Focus
Destination:
Console and stdout
Module:
casstop
Parent topic: CASST0000 - CASST0020


CASST0019S

The Safmgr failed to initialize and, therefore, Enterprise Server will be shutdown.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
The reporting Enterprise Server is terminated.
Resolution:
Correct the Safmgr initialization problem and restart ES.
Destination:
Console and stdout
Module:
any ES process (cascpsfi)
Parent topic: CASST0000 - CASST0020


CASST0020I

The shutdown is in progress, use force if the region did not stop in a timely fashion.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
None.
Resolution:
None.
Destination:
Console and stdout
Module:
casstop
Parent topic: CASST0000 - CASST0020


CASST4000 - CASST4111

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASST4000I
    A request to shutdown the Micro Focus Transaction System has been entered using either the CQIT transaction or the PERFORM SHUTDOWN command.
  • CASST4001I
    A request to shutdown the Micro Focus Transaction System IMMEDIATELY has been entered using the PERFORM SHUTDOWN command.
  • CASST4002E
    The shutdown request was rejected because the system was already in shutdown or was never successfully started.
  • CASST4010I
    Shutdown processing has begun using the indicated PLT.
  • CASST4011I
    Shutdown processing has begun; no PLTSD was specified for PLT processing.
  • CASST4020I
    The PLTSD Phase 1 processing has been completed.
  • CASST4021E
    The PLTSD processing encountered an error in processing program list or one of the programs in the list ABENDed.
  • CASST4022S
    The PLT processing transaction program, dfhzplt, could not be found.
  • CASST4090I
    The attached terminal is automatically disconnected when a shutdown request is processed.
  • CASST4100I
    A request to shutdown the Micro Focus Transaction System has been entered using either the CQIT transaction or the PERFORM SHUTDOWN command.
  • CASST4101I
    A request to shutdown the Micro Focus Transaction System IMMEDIATELY has been entered using the PERFORM SHUTDOWN command.
  • CASST4102E
    The shutdown request was rejected because the system was already in shutdown or was never successfully started.
  • CASST4110I
    Shutdown processing has begun using the indicated PLT.
  • CASST4111I
    Shutdown processing has begun; no PLTSD was specified for PLT processing.
Parent topic: CASST Error Messages


CASST4000I

A request to shutdown the Micro Focus Transaction System has been entered using either the CQIT transaction or the PERFORM SHUTDOWN command.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown processing is started.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4001I

A request to shutdown the Micro Focus Transaction System IMMEDIATELY has been entered using the PERFORM SHUTDOWN command.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown processing is started; no PLT processing will be done.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4002E

The shutdown request was rejected because the system was already in shutdown or was never successfully started.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
None
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4010I

Shutdown processing has begun using the indicated PLT.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
PLTSD Processing is started, shutdown proceeding normally.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4011I

Shutdown processing has begun; no PLTSD was specified for PLT processing.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown proceeding normally without PLT processing.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4020I

The PLTSD Phase 1 processing has been completed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown proceeding normally.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4021E

The PLTSD processing encountered an error in processing program list or one of the programs in the list ABENDed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown processing aborted.
Resolution:
Do a SHUTDOWN IMMMEDIATE to bypass PLTSD processing.
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4022S

The PLT processing transaction program, dfhzplt, could not be found.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown processing aborted.
Resolution:
Do a SHUTDOWN IMMMEDIATE to bypass PLTSD processing.
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4090I

The attached terminal is automatically disconnected when a shutdown request is processed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Disconnect the terminal requesting shutdown.
Resolution:
None
Destination:
Terminal
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4100I

A request to shutdown the Micro Focus Transaction System has been entered using either the CQIT transaction or the PERFORM SHUTDOWN command.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown processing is started.
Resolution:
None
Destination:
Console
Module:
casrdo11
Parent topic: CASST4000 - CASST4111


CASST4101I

A request to shutdown the Micro Focus Transaction System IMMEDIATELY has been entered using the PERFORM SHUTDOWN command.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown processing is started; no PLT processing will be done.
Resolution:
None
Destination:
Console
Module:
casrdo11
Parent topic: CASST4000 - CASST4111


CASST4102E

The shutdown request was rejected because the system was already in shutdown or was never successfully started.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
None
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzcqit
Parent topic: CASST4000 - CASST4111


CASST4110I

Shutdown processing has begun using the indicated PLT.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
PLTSD Processing is started, shutdown proceeding normally.
Resolution:
None
Destination:
Console
Module:
casrdo11
Parent topic: CASST4000 - CASST4111


CASST4111I

Shutdown processing has begun; no PLTSD was specified for PLT processing.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown proceeding normally without PLT processing.
Resolution:
None
Destination:
Console
Module:
casrdo11
Parent topic: CASST4000 - CASST4111


CASST5000 - CASST6002

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASST5000I
    Shutdown PLT processing has started using the plt-name list.
  • CASST5001I
    Shutdown PLT processing was entered, but no list was specified.
  • CASST5002S
    The Resource Definition file could not be opened to read the PLTSD program list table.
  • CASST5003S
    The specified PLTSD program list table could not be found in the Resource Definition file.
  • CASST5004S
    The specified PLTSD program list table was not present in the installed PPT.
  • CASST5005S
    A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTSD processing.
  • CASST5006S
    The named program specified could not be found and resulted in a PGMIDERR.
  • CASST5010I
    Shutdown PLT processing has completed successfully using the plt-name list.
  • CASST5020I
    Shutdown Phase 2 PLT processing has started using the plt-name list.
  • CASST5021I
    Shutdown Phase 2 PLT processing was entered, but no list was specified.
  • CASST5022S
    The Resource Definition file could not be opened to read the PLTSD program list table.
  • CASST5023S
    The specified PLTSD program list table could not be found in the Resource Definition file.
  • CASST5024S
    The specified PLTSD program list table was not present in the installed PPT.
  • CASST5025S
    A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTSD processing.
  • CASST5026S
    The named program specified could not be found and resulted in a PGMIDERR.
  • CASST5030I
    Shutdown Phase 2 PLT processing has completed successfully using the plt-name list.
  • CASST5201I
    The spool service has terminated normally
  • CASST5230I
    The Event Process is terminating.
  • CASST5231I
    The Event Manager Process has terminated.
  • CASST6002I
    The MQSeries trigger monitor program (CKTI) has disconnected from the queue manager and is terminating
Parent topic: CASST Error Messages


CASST5000I

Shutdown PLT processing has started using the plt-name list.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT processing proceeds normally
Resolution:
None
Destination:
console (and terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5001I

Shutdown PLT processing was entered, but no list was specified.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Shutdown proceeds normally
Resolution:
None
Destination:
console (and terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5002S

The Resource Definition file could not be opened to read the PLTSD program list table.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT Processing is bypassed, shutdown continues
Resolution:
None
Destination:
console (and terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5003S

The specified PLTSD program list table could not be found in the Resource Definition file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT Processing is bypassed, shutdown continues
Resolution:
None
Destination:
console (and terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5004S

The specified PLTSD program list table was not present in the installed PPT.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT Processing is bypassed, shutdown continues
Resolution:
None
Destination:
console (and terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5005S

A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTSD processing.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT processing is terminated; Shutdown is aborted
Resolution:
Do a SHUTDOWN IMMMEDIATE to bypass PLTSD processing. Determine the cause of the transaction program abend and correct it. If the problem cannot be determined, the Resource Definitions can be updated to omit the program from the PLT or to use a different (or no) PLT.
Destination:
console (and terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5006S

The named program specified could not be found and resulted in a PGMIDERR.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT processing continues, the named program is ignored
Resolution:
Make sure that the program exists and has been compiled correctly. The compiled program must been in a directory specified on TRANPATH.
Destination:
console
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5010I

Shutdown PLT processing has completed successfully using the plt-name list.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Shutdown proceeds normally
Resolution:
None
Destination:
console (and terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5020I

Shutdown Phase 2 PLT processing has started using the plt-name list.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
PLT processing proceeds normally
Resolution:
None
Destination:
console (and terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5021I

Shutdown Phase 2 PLT processing was entered, but no list was specified.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Shutdown proceeds normally
Resolution:
None
Destination:
console (and terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5022S

The Resource Definition file could not be opened to read the PLTSD program list table.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
PLT Processing is bypassed, shutdown continues.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5023S

The specified PLTSD program list table could not be found in the Resource Definition file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
PLT Processing is bypassed, shutdown continues.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5024S

The specified PLTSD program list table was not present in the installed PPT.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
PLT Processing is bypassed, shutdown continues.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5025S

A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTSD processing.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
PLT processing is terminated; Shutdown is aborted.
Resolution:
Do a SHUTDOWN IMMMEDIATE to bypass PLTSD processing. Determine the cause of the transaction program abend and correct it. If the problem cannot be determined, the Resource Definitions can be updated to omit the program from the PLT or to use a different (or no) PLT.
Destination:
Console (and Terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5026S

The named program specified could not be found and resulted in a PGMIDERR.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
PLT processing continues, the named program is ignored.
Resolution:
Make sure that the program exists and has been compiled correctly. The compiled program must been in a directory specified on TRANPATH.
Destination:
Console
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5030I

Shutdown Phase 2 PLT processing has completed successfully using the plt-name list.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System action:
Shutdown proceeds normally.
Resolution:
None
Destination:
Console (and Terminal)
Module:
dfhzplt
Parent topic: CASST5000 - CASST6002


CASST5201I

The spool service has terminated normally
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhgspol
Parent topic: CASST5000 - CASST6002


CASST5230I

The Event Process is terminating.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
console
Module:
casevmgr
Parent topic: CASST5000 - CASST6002


CASST5231I

The Event Manager Process has terminated.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
console
Module:
casevmgr
Parent topic: CASST5000 - CASST6002


CASST6002I

The MQSeries trigger monitor program (CKTI) has disconnected from the queue manager and is terminating
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhtmqgw
Parent topic: CASST5000 - CASST6002


CASXO Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASXO0001 - CASXO0015
  • CASXO0016 - CASXO0029
Parent topic: Enterprise Server Error Messages


CASXO0001 - CASXO0015

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASXO0001S
    The Resource manager for the XAT resource returned a non-zero value to the xa_open call. Where the return code means :
  • CASXO0002S
    The Switch Load Module for the XAT resource failed to load
  • CASXO0003S
    The Resource manager for the XAT resource returned a non-zero value to the xa_start call.
  • CASXO0004S
    The Resource manager for the XAT resource returned a non-zero value to the xa_end call.
  • CASXO0005S
    The Resource manager for the XAT resource returned a non-zero value to the xa_prepare call.
  • CASXO0006S
    The Resource manager for the XAT resource reported that due to a failure the work done on behalf of the transaction may have been heuristically completed.
  • CASXO0007S
    The Resource manager for the XAT resource reported that due to a heuristic decision the work done on behalf of the transaction has been committed.
  • CASXO0008S
    The Resource manager for the XAT resource reported that due to a heuristic decision the work done on behalf of the transaction has been rolled back.
  • CASXO0009S
    The Resource manager for the XAT resource reported that due to a heuristic decision the work done on behalf of the transaction has been partially committed and partially rolled back.
  • CASXO0010S
    The Resource manager for the XAT resource returned a non-zero value to the xa_commit call.
  • CASXO0011S
    The Resource manager for the XAT resource returned a non-zero value to the xa_rollback call.
  • CASXO0012S
    The Resource manager for the XAT resource returned a non-zero value to the xa_close call.
  • CASXO0013S
    The Resource manager for the XAT resource indicated it had rolled back the transaction.
  • CASXO0014S
    The Resource manager for the XAT resource returned a non-zero value to the xa_commit call.
  • CASXO0015I
    The XA resource manager's switch module was loaded successfully and the xa-open processing called.
Parent topic: CASXO Error Messages


CASXO0001S

The Resource manager for the XAT resource returned a non-zero value to the xa_open call. Where the return code means :
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • -1 An error occured in the transaction manager
  • -2 Asynchronous operation already outstanding
  • -3 A resource manager error occurred
  • -4 The XID is not valid
  • -5 Invalid arguments were given
  • -6 Routine invoked in an improper context
  • -7 Resource Manager unavailable
  • -8 the XID already exists
  • -9 Resource Manager doing work outside global transaction
System Action:
The region will not start
Resolution:
Check that the Database Manager has been started, if necessary
Destination:
console and standard error
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0002S

The Switch Load Module for the XAT resource failed to load
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will not start
Resolution:
Check that the Switch Load Module is on the libpath or in $CASDIR\lib
Destination:
console and standard error
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0003S

The Resource manager for the XAT resource returned a non-zero value to the xa_start call.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • -2 Asynchronous operation already outstanding
  • -3 A resource manager error occurred
  • -4 The XID is not valid
  • -5 Invalid arguments were given
  • -6 Routine invoked in an improper context
  • -7 Resource Manager unavailable
  • -8 the XID already exists
  • -9 Resource Manager doing work outside global transaction
  • The following indicate the transaction is marked as roll-back only
  • 100 The resource manager marked the transaction roll-back
  • only for an unspecified reason.
  • 101 A communication failure occurred
  • 102 The resource manager detected a deadlock
  • 103 The resource manager detected a violation of the integrity
  • of its resources
  • 104 The resource manager marked the transaction roll-back
  • only for a reason not in this list.
  • 105 A protocol error occurred in the resource manager
  • 106 The work represented by this transaction took too long
  • 107 The resource manager detected a transient error
System Action:
The Transaction is abnormally terminated
Resolution:
Check that the Resource Manager is still available
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0004S

The Resource manager for the XAT resource returned a non-zero value to the xa_end call.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • -2 Asynchronous operation already outstanding
  • -3 A resource manager error occurred
  • -4 The XID is not valid
  • -5 Invalid arguments were given
  • -6 Routine invoked in an improper context
  • -7 Resource Manager unavailable
  • -8 the XID already exists
  • -9 Resource Manager doing work outside global transaction
  • The following indicate the transaction is marked as roll-back only
  • 100 The resource manager marked the transaction roll-back
  • only for an unspecified reason.
  • 101 A communication failure occurred
  • 102 The resource manager detected a deadlock
  • 103 The resource manager detected a violation of the integrity
  • of its resources
  • 104 The resource manager marked the transaction roll-back
  • only for a reason not in this list.
  • 105 A protocol error occurred in the resource manager
  • 106 The work represented by this transaction took too long
  • 107 The resource manager detected a transient error
System Action:
The Transaction is abnormally terminated
Resolution:
Check that the Resource Manager is still available
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0005S

The Resource manager for the XAT resource returned a non-zero value to the xa_prepare call.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • -2 Asynchronous operation already outstanding
  • -3 A resource manager error occurred
  • -4 The XID is not valid
  • -5 Invalid arguments were given
  • -6 Routine invoked in an improper context
  • -7 Resource Manager unavailable
  • -8 the XID already exists
  • -9 Resource Manager doing work outside global transaction
  • The following indicate the transaction is marked as roll-back only
  • 100 The resource manager marked the transaction roll-back
  • only for an unspecified reason.
  • 101 A communication failure occurred
  • 102 The resource manager detected a deadlock
  • 103 The resource manager detected a violation of the integrity
  • of its resources
  • 104 The resource manager marked the transaction roll-back
  • only for a reason not in this list.
  • 105 A protocol error occurred in the resource manager
  • 106 The work represented by this transaction took too long
  • 107 The resource manager detected a transient error
System Action:
The Transaction is abnormally terminated
Resolution:
Check that the Resource Manager is still available
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0006S

The Resource manager for the XAT resource reported that due to a failure the work done on behalf of the transaction may have been heuristically completed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The state of the transaction is undefined
Resolution:
Contact your administrator for the resource
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0007S

The Resource manager for the XAT resource reported that due to a heuristic decision the work done on behalf of the transaction has been committed.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The state of the transaction is undefined
Resolution:
Contact your administrator for the resource
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0008S

The Resource manager for the XAT resource reported that due to a heuristic decision the work done on behalf of the transaction has been rolled back.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The state of the transaction is undefined
Resolution:
Contact your administrator for the resource
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0009S

The Resource manager for the XAT resource reported that due to a heuristic decision the work done on behalf of the transaction has been partially committed and partially rolled back.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The state of the transaction is undefined
Resolution:
Contact your administrator for the resource
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0010S

The Resource manager for the XAT resource returned a non-zero value to the xa_commit call.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • -2 Asynchronous operation already outstanding
  • -3 A resource manager error occurred
  • -4 The XID is not valid
  • -5 Invalid arguments were given
  • -6 Routine invoked in an improper context
  • -7 Resource Manager unavailable
  • -8 the XID already exists
  • -9 Resource Manager doing work outside global transaction
  • The following indicate the transaction is marked as roll-back only
  • 100 The resource manager marked the transaction roll-back
  • only for an unspecified reason.
  • 101 A communication failure occurred
  • 102 The resource manager detected a deadlock
  • 103 The resource manager detected a violation of the integrity
  • of its resources
  • 104 The resource manager marked the transaction roll-back
  • only for a reason not in this list.
  • 105 A protocol error occurred in the resource manager
  • 106 The work represented by this transaction took too long
  • 107 The resource manager detected a transient error
System Action:
The Transaction is abnormally terminated
Resolution:
Check that the Resource Manager is still available
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0011S

The Resource manager for the XAT resource returned a non-zero value to the xa_rollback call.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • -2 Asynchronous operation already outstanding
  • -3 A resource manager error occurred
  • -4 The XID is not valid
  • -5 Invalid arguments were given
  • -6 Routine invoked in an improper context
  • -7 Resource Manager unavailable
  • -8 the XID already exists
  • -9 Resource Manager doing work outside global transaction
  • The following indicate the transaction is marked as roll-back only
  • 100 The resource manager marked the transaction roll-back only for an unspecified reason.
  • 101 A communication failure occurred
  • 102 The resource manager detected a deadlock
  • 103 The resource manager detected a violation of the integrity of its resources
  • 104 The resource manager marked the transaction roll-only for a reason not in this list.
  • 105 A protocol error occurred in the resource manager
  • 106 The work represented by this transaction took too long
  • 107 The resource manager detected a transient error
System Action:
The Transaction is abnormally terminated
Resolution:
Check that the Resource Manager is still available
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0012S

The Resource manager for the XAT resource returned a non-zero value to the xa_close call.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • -2 Asynchronous operation already outstanding
  • -3 A resource manager error occurred
  • -5 Invalid arguments were given
  • -6 Routine invoked in an improper context
System Action:
None
Resolution:
Contact your system administrator for the resource
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0013S

The Resource manager for the XAT resource indicated it had rolled back the transaction.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • 100 The resource manager marked the transaction roll-back only for an unspecified reason.
  • 101 A communication failure occurred
  • 102 The resource manager detected a deadlock
  • 103 The resource manager detected a violation of the integrity of its resources
  • 104 The resource manager marked the transaction roll-back only for a reason not in this list.
  • 105 A protocol error occurred in the resource manager
  • 106 The work represented by this transaction took too long
  • 107 The resource manager detected a transient error
System Action:
None
Resolution:
Contact your system administrator for the resource
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0014S

The Resource manager for the XAT resource returned a non-zero value to the xa_commit call.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • -2 Asynchronous operation already outstanding
  • -3 A resource manager error occurred
  • -4 The XID is not valid
  • -5 Invalid arguments were given
  • -6 Routine invoked in an improper context
  • -7 Resource Manager unavailable
  • -8 the XID already exists
  • -9 Resource Manager doing work outside global transaction
System Action:
The Transaction is abnormally terminated
Resolution:
Check that the Resource Manager is still available
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0015I

The XA resource manager's switch module was loaded successfully and the xa-open processing called.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhexa
Parent topic: CASXO0001 - CASXO0015


CASXO0016 - CASXO0029

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • CASXO0016S
    The XA resource manager's switch module had been previously loaded successfully by another server but failed to intiialize on this process.
  • CASXO0017S
    An unrecoverable error occured interfacing with the XA Resouce Manager.
  • CASXO0018S
    The Resource manager for the XAT resource returned a non-zero value to the xa_end call.
  • CASXO0019S
    The Switch Load Module for the XAT resource failed to load the necessary DLLs or .so programs. The returned pointer was null.
  • CASXO0020I
    The XA resource manager's switch module was loaded successfully.
  • CASXO0021I
    The XA resource manager's switch module contained appropriate support for local transactions.
  • CASXO0022W
    The XA resource manager's switch module did not contain support for local transaction commit/rollback functions.
  • CASXO0023S
    A severe error occured interfacing with the XA Resouce Manager.
  • CASXO0024I
    A user disabled the XA Resouce Manager.
  • CASXO0025I
    A user enabled the XA Resouce Manager.
  • CASXO0026I
    A user requested support for one phase commit only.
  • CASXO0027I XA recovery committed in-doubt transaction XID transaction number branch XID transaction branch number on RM Resource manager
    Enterprise Server recovery has committed in-doubt transaction XID transaction number branch XID transaction branch number# for resource manager Resource manager.
  • CASXO0028I XA recovery rolled back in-doubt transaction XID transaction number branch XID transaction branch number on RM Resource manager
    Enterprise Server recovery has rolled back in-doubt transaction XID transaction number branch XID transaction branch number# for resource manager Resource manager.
  • CASXO0029I
    The XA log has rolled back in-doubt transaction XID transaction number branch XID transaction branch number.
Parent topic: CASXO Error Messages


CASXO0016S

The XA resource manager's switch module had been previously loaded successfully by another server but failed to intiialize on this process.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
Determine the cause of the failure and restart the system
Destination:
console
Module:
dfhexa
Parent topic: CASXO0016 - CASXO0029


CASXO0017S

An unrecoverable error occured interfacing with the XA Resouce Manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will not be called for future transactions
Resolution:
Determine the cause of the failure and restart the system
Destination:
console
Module:
dfhexa
Parent topic: CASXO0016 - CASXO0029


CASXO0018S

The Resource manager for the XAT resource returned a non-zero value to the xa_end call.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

The return codes are:

  • -2 Asynchronous operation already outstanding
  • -3 A resource manager error occurred
  • -4 The XID is not valid
  • -5 Invalid arguments were given
  • -6 Routine invoked in an improper context
  • -7 Resource Manager unavailable
  • -8 the XID already exists
  • -9 Resource Manager doing work outside global transaction
  • The following indicate the transaction is marked as roll-back only
  • 100 The resource manager marked the transaction roll-back only for an unspecified reason.
  • 101 A communication failure occurred
  • 102 The resource manager detected a deadlock
  • 103 The resource manager detected a violation of the integrity of its resources
  • 104 The resource manager marked the transaction roll-back
  • only for a reason not in this list.
  • 105 A protocol error occurred in the resource manager
  • 106 The work represented by this transaction took too long
  • 107 The resource manager detected a transient error
System Action:
The Transaction is abnormally terminated
Resolution:
Check that the Resource Manager is still available
Destination:
terminal
Module:
dfhexa
Parent topic: CASXO0016 - CASXO0029


CASXO0019S

The Switch Load Module for the XAT resource failed to load the necessary DLLs or .so programs. The returned pointer was null.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The region will not start
Resolution:
Check that the programs loaded by the Switch Load Module are on the path or libpath or in $CASDIR\lib
Destination:
console and standard error
Module:
dfhexa
Parent topic: CASXO0016 - CASXO0029


CASXO0020I

The XA resource manager's switch module was loaded successfully.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhexa
Parent topic: CASXO0016 - CASXO0029


CASXO0021I

The XA resource manager's switch module contained appropriate support for local transactions.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
None
Resolution:
None
Destination:
console
Module:
dfhexa
Parent topic: CASXO0016 - CASXO0029


CASXO0022W

The XA resource manager's switch module did not contain support for local transaction commit/rollback functions.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
Transactional support for JCL via IKJEFT01 will not be supported
Resolution:
None
Destination:
console
Module:
dfhexa
Parent topic: CASXO0016 - CASXO0029


CASXO0023S

A severe error occured interfacing with the XA Resouce Manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will not be called for future transactions
Resolution:
Determine the cause of the failure and re-enable it
Destination:
console
Module:
dfheserv
Parent topic: CASXO0016 - CASXO0029


CASXO0024I

A user disabled the XA Resouce Manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will not be called for future transactions
Resolution:
None
Destination:
console
Module:
casrdo81
Parent topic: CASXO0016 - CASXO0029


CASXO0025I

A user enabled the XA Resouce Manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will be called for future transactions
Resolution:
None
Destination:
console
Module:
casrdo81
Parent topic: CASXO0016 - CASXO0029


CASXO0026I

A user requested support for one phase commit only.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The XA Resource Manager will be called for future transactions
Resolution:
None
Destination:
console
Module:
dfhexa
Parent topic: CASXO0016 - CASXO0029


CASXO0027I XA recovery committed in-doubt transaction XID transaction number branch XID transaction branch number on RM Resource manager

Enterprise Server recovery has committed in-doubt transaction XID transaction number branch XID transaction branch number# for resource manager Resource manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The transaction has been committed on this resource manager.
Resolution:
None.
Module:
dfhexarc
Destination:
Console.
Parent topic: CASXO0016 - CASXO0029


CASXO0028I XA recovery rolled back in-doubt transaction XID transaction number branch XID transaction branch number on RM Resource manager

Enterprise Server recovery has rolled back in-doubt transaction XID transaction number branch XID transaction branch number# for resource manager Resource manager.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The transaction has been rolled back on this resource manager.
Resolution:
None.
Module:
dfhexarc
Destination:
Console.
Parent topic: CASXO0016 - CASXO0029


CASXO0029I

The XA log has rolled back in-doubt transaction XID transaction number branch XID transaction branch number.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
System Action:
The transaction has been rolled back on this resource manager.
User response:
None
Module:
castsc
Destination:
Console
Parent topic: CASXO0016 - CASXO0029


User Exits

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This contains the available user exits:

  • Exit Points
  • Support Functions
  • Structures
Parent topic: Enterprise Server Reference


Exit Points

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following exit points are available:

  • Exit Interface Definition
    Contains the information required by the exit routines for processing at each exit point. A pointer to this structure, together with the exit point identifier, is passed to each exit function.
  • External Data Value Modification - Input Parameter (Exit Point 1)
    Allows you to override the external value provided by the client request for the given COBOL program's Linkage Section item.
  • Internal Data Value Modification - Input Parameter (Exit Point 2)
    Allows you to override the internal value provided by the client request for the given COBOL program's Linkage Section item.
  • Unmapped Named External Input Parameter (Exit Point 3)
    Allows you to handle an unmapped named external input parameter that has been specified in the client request.
  • End of Input Request Processing (Exit Point 4)
    Allows you to initialize parameter values in the internal data areas addressed by argv other than those initialised during external parameter mapping.
  • Start of Response Processing (Exit Point 5)
    Allows you to bypass completely the default response processing.
  • Internal Data Value Modification - Output Parameter (Exit Point 6)
    Allows you to override the internal data value created during the execution of the application.
  • External Data Value Modification - Output Parameter (Exit Point 7)
    Allows you to override the internal data value created during the execution of the application.
  • End of Response Processing (Exit Point 8)
    Allows you to override the internal data value created during the execution of the application.
  • End of Request Processing (Exit Point 9)
    Allows you to release any resources that were allocated in exit points 0 through 8.
Parent topic: User Exits


Exit Interface Definition

Contains the information required by the exit routines for processing at each exit point. A pointer to this structure, together with the exit point identifier, is passed to each exit function.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
Exit point in the request handler:
1 | External data value modification - input parameter
2 | Internal data value modification - input parameter
3 | Unmapped named external input parameter
4 | End of input request processing
5 | Start of response processing
6 | Internal data value modification - output parameter
7 | External data value modification - output parameter
8 | End of response processing
9 | End of request processing
exit_info
Usage depends on the exit point

On Exit:

exit_info
Usage depends on the exit point

Return codes:

Depends on the exit point.

Parent topic: Exit Points


External Data Value Modification - Input Parameter (Exit Point 1)

Allows you to override the external value provided by the client request for the given COBOL program's Linkage Section item.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
1 = External data value modification - input parameter
exit_info
version | Version of structure format
flags | 0
ext_value_size | Size of data addressed by ext_value
funcs | User exit support functions
field_name | Name of data item in COBOL program's Linkage Section
ext_param_name | Name of external parameter
ext_value | External data value associated with field_name
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

exit_info
ext_value_size | Size of data addressed by ext_value. Needs to be updated only if the user exit allocates memory for a new ext_value string
ext_value | External data value to be associated with field_name. Needs to be updated only if the user exit allocates memory for a new ext_value string
exit_data | User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default parameter mapping
IDP_EXIT_STOP
1 = Terminate mapping processing. No service will be invoked. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden the supplied external value. Use this value to perform default mapping for the given COBOL program Linkage Section field name.

Comments:

This exit gives you the opportunity to override the external value provided by the client request for the given COBOL program Linkage Section field name. If the exit chooses to override the external value, it must return IDP_EXIT_HANDLED and either update ext_value in place (if the replacement value is less or equal to ext_value_size), or allocate a replacement string using the support function fn_alloc_mem and set ext_value and ext_value_size accordingly. The request handler then performs default mapping for the original (IDP_EXIT_CONTINUE) or overridden (IDP_EXIT_HANDLED) external data value.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


Internal Data Value Modification - Input Parameter (Exit Point 2)

Allows you to override the internal value provided by the client request for the given COBOL program's Linkage Section item.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
2 = Internal data value modification - input parameter
exit_info
version | Version of structure format
flags | 0
data_size | Size of data ddressed by data_ptr
ext_value_size | Size of data addressed by ext_value
funcs | User exit support functions
field_name | Name of data item in COBOL program's Linkage Section
data_ptr | Internal data value associated with field_name
ext_param_name | Name of external parameter
ext_value | External data value associated with field_name
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

exit_info
exit_data User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default parameter mapping
IDP_EXIT_STOP
1 = Terminate mapping processing. No service will be invoked. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden the supplied internal value

Comments:

This exit gives you the opportunity to override the internal data value created by the request handler’s default mapping from the external data value provided by the client request for the given COBOL program Linkage Section data item name. data_ptr addresses the memory created by the request handler to be passed to the user program as part of its Linkage Section. If the exit chooses to override this parameter, it must only modify up to data_size bytes starting at data_ptr, and must return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


Unmapped Named External Input Parameter (Exit Point 3)

Allows you to handle an unmapped named external input parameter that has been specified in the client request.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
3 = Unmapped named external input parameter
exit_info
version
Version of structure format
flags
0
ext_value_size
Size of data addressed by ext_value
funcs
User exit support functions
ext_param_name
Name of external parameter
ext_value
External data value associated with field_name
request_cxt
version | Version of structure format
argc | Parameter count of loaded service
service_type | Type of client request
flags | Request context control flags
argv | Parameter list of loaded service
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
epoint_name | Name of the entry point to invoke
exit_data
User exit-specific data

On Exit:

exit_info
flags
0
request_cxt
accept_buf_len | Length of data in accept_buf
cmd_line _len | Length of data in cmd_line
flags | Request context control flags
accept_buf | Data to be used for ANSI ACCEPT statements
cmd_line | String to be used to resolve ACCEPT FROM COMMAND-LINE statements
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with processing
IDP_EXIT_STOP
1 = Terminate mapping processing. No service will be invoked. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden one or more of the returned request context fields

Comments:

This exit gives you the opportunity to handle an unmapped named external input parameter that has been specified in the client request. The exit program would typically handle the parameter by setting an appropriate value in one or more of the data areas addressed by argv, setting up data to be used for ANSI ACCEPT statements (accept_buf), or setting up the application’s command line (cmd_line). The exit should use the fn_alloc_mem support function of the exit_info funcs structure to allocate any memory used for the setting up of accept_buf or cmd_line. If the exit chooses to override any of the request context fields, it must return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


End of Input Request Processing (Exit Point 4)

Allows you to initialize parameter values in the internal data areas addressed by argv other than those initialised during external parameter mapping.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32   exit_point,
                                  IDP_EXIT_INFO *exit_info);

On Entry:

exit point
4 = End of input request processing
exit_info
version
Version of structure format
flags
0
funcs
User exit support functions
request_cxt
version | Version of structure format
argc | Parameter count of loaded service
service_type | Type of client request
accept_buf_len | Length of data in accept_buf
cmd_line_len | Length of data in cmd_line
flags | Request context control flags
argv | Parameter list of loaded service
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
epoint_name | Name of the entry point to invoke
accept_buf | Data to be used for ANSI ACCEPT statements
cmd_line | String to be used to resolve ACCEPT FROM COMMAND-LINE statements
exit_data
User exit-specific data

On Exit:

exit info
flags
0
request_cxt
argc | Parameter count of loaded service
service_type | Type of client request
accept_buf_len | Length of data in accept_buf
cmd_line_len | Length of data in cmd_line
flags | Request context control flags
argv | Parameter list of loaded service
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
epoint_name | Name of the entry point to invoke
accept_buf | Data to be used for ANSI ACCEPT statements
cmd_line | String to be used to resolve ACCEPT FROM COMMAND-LINE statements
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with processing
IDP_EXIT_STOP
1 = Terminate mapping processing. No service will be invoked. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden one or more of the returned request context fields

Comments:

This exit gives you the opportunity to initialize parameter values in the internal data areas addressed by argv other than those initialized during external parameter mapping. The exit can optionally modify any of the returned request fields listed above. The exit should use the fn_alloc_mem support function of the exit_info funcs structure to allocate any memory used to replace request context strings (for example, service_name or epoint_name) or argv fields. If the exit chooses to override any of the request context fields, it must return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


Start of Response Processing (Exit Point 5)

Allows you to bypass completely the default response processing.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
5 = Start of response processing
exit_info
version
Version of structure format
flags
0
funcs
User exit support functions
request_cxt
version | Version of structure format
argc | Parameter count of loaded service
return_code | Service's return code, or run-time error generated by service
service_type | Type of client request
display_buf_len | Length of data in display_buf
flags | Request context control flags
protocol_attrs | An array of pointers to protocol-specifc attributes
argv | Parameter list of loaded service
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
display_buf | Concatenation of strings output by ANSI DISPLAY statements
response
flagss | Control flags
response_type | Server's response type
exit_data
User exit-specific data

On Exit:

exit_info
flags
0
response
response_len | Length of response_buf
flags | Control flags
response_buf | Server's response buffer
content_type | NULL-terminated content type string (HTTP) only
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default response processing
IDP_EXIT_STOP
1 = Terminate mapping processing. An error response will be required
IDP_EXIT_HANDLED
2 = The entire response has been built by the exit. No further processing is required. The response is ready to be sent back to the client.

Comments:

This exit gives you the opportunity to bypass completely the default response processing. If the exit wants the default response processing to be bypassed, it must set up the response fields indicated above as being returned fields, using the fn_alloc_mem support function of the exit_info funcs structure to allocate the memory for the response buffer, and return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


Internal Data Value Modification - Output Parameter (Exit Point 6)

Allows you to override the internal data value created during the execution of the application.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
6 = Internal data value modification - output parameter
exit_info
version | Version of structure format
flags | 0
data_size | Size of data addressed by the data_ptr field
funcs | User exit support functions
field name | Name of data item in COBOL program's Linkage Section
data_ptr | Internal data value associated with field_name
ext_param_name | External parameter name
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

exit_info
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default parameter mapping
IDP_EXIT_STOP
1 = Terminate mapping processing. An error response will be required
IDP_EXIT_HANDLED
The exit has overridden the supplied internal data value

Comments:

This exit gives you the opportunity to override the internal data value created during the execution of the application. data_ptr addresses the memory assigned to the internal data value. If the exit chooses to override this parameter, it must only modify up to data_size bytes starting at data_ptr, and must return IDP_EXIT_HANDLED. The request handler will subsequently perform default mapping for the original (IDP_EXIT_CONTINUE) or overridden (IDP_EXIT_HANDLED) internal data value.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


External Data Value Modification - Output Parameter (Exit Point 7)

Allows you to override the internal data value created during the execution of the application.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
7 = External data value modification - output parameter
exit_info
version | Version of structure format
flags | 0
ext_value_size | Size of data addressed by the ext_value field
funcs | User exit support functions
field name | Name of data item in COBOL program's Linkage Section
ext_param_name | Name of external parameter
ext_value | External data value associated with the field_name field
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

exit_info
ext_value_size | Size of data addressed by the ext_value field. Needs to be updated only if the user exit allocates memory for a new ext_value string
ext_value | External data value to be associated with field_name. Needs to be updated only if the user exit allocates memory for a new ext_value string
exit_data | User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with default parameter mapping
IDP_EXIT_STOP
1 = Terminate mapping processing. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden the supplied external data value. Use this value to perform default mapping for the given COBOL Linkage Section field name
IDP_EXIT_OMIT
3 = The exit has determined that the given parameter should not be included in the response

Comments:

This exit gives you the opportunity to override the external value created by the request handler in its default mapping processing for the given COBOL Linkage Section field name. If the exit chooses to override the external value, it must return IDP_EXIT_HANDLED and either update ext_value in place (if the replacement value is less or equal to ext_value_size), or allocate a replacement string using the support function fn_alloc_mem and set ext_value and ext_value_size accordingly. The request handler will use the returned ext_value (IDP_EXIT_CONTINUE or IDP_EXIT_HANDLED) in its default response processing.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


End of Response Processing (Exit Point 8)

Allows you to override the internal data value created during the execution of the application.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
8 = End of response processing
exit_info
version
Version of structure format
flags
0
funcs
User exit support functions
request_cxt
version | Version of structure format
service_type | Type of client request
display_buf_len | Length of data in display_buf
flags | Request context control flags
service_name | Name of loaded service
pgm_name | Name of the main program associated with the service
epoint_name | Name of the entry point to invoke
display_buf | Concatenation of strings output by ANSI DISPLAY statements
response
response_len | Length of response_buf
flags | Control flags
response_buf | Response buffer created by default mapping or overridden by the exit
content_type | NULL-terminated content type string (HTTP only)
exit_data
User exit-specific data

On Exit:

exit_info
response
response_len | Length of response_buf
response_buf | Response buffer
content_type | NULL-terminated content type string (HTTP only)
exit_data
User exit-specific data

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with processing
IDP_EXIT_STOP
1 = Terminate response processing. The default response is not to be sent. An error response will be required
IDP_EXIT_HANDLED
2 = The exit has overridden the default response

Comments:

This exit gives you the opportunity to override the full response generated by default mapping. The exit can optionally modify any of the returned request fields listed above. The exit should use the fn_alloc_mem support function of the exit_info funcs structure to allocate any memory used to replace the response_buf field. If the exit chooses to override any of the response structure fields, it must return IDP_EXIT_HANDLED.

The user exit program owns the exit_data field of the IDP_EXIT_INFO structure. You would typically use it to preserve context information between exit point invocations. You can use it when returning any of the IDP_EXIT_ return values.

Parent topic: Exit Points


End of Request Processing (Exit Point 9)

Allows you to release any resources that were allocated in exit points 0 through 8.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDP_EXIT)(mf_uns32      exit_point,
                                     IDP_EXIT_INFO *exit_info);

On Entry:

exit point
9 = End of request processing
exit_info
version | Version of structure format
flags | 0
funcs | User exit support functions
request_cxt | Request context
exit_data | User exit-specific data

On Exit:

None

Return codes:

IDP_EXIT_CONTINUE
0 = Continue with processing
IDP_EXIT_STOP
1 = An error has occurred during end of request processing

Comments:

This exit gives you the opportunity to release any resources that were allocated in exit points 0 through 8.

Parent topic: Exit Points


Support Functions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following support functions are available:

  • PFI
    A generic type definition for a function that returns an integer value.
  • PFI_IDPES_FN_DISPLAY_TO_UTF16
    Converts COBOL DISPLAY encoded strings to UTF-16 encoded strings.
  • PFI_IDPES_FN_UTF16_TO_DISPLAY
    Converts UTF-16 encoded strings to COBOL DISPLAY encoded strings.
  • PFV_IDPES_FN_ALLOC_MEM
    Allocates memory for user exits to use.
  • PFV_IDPES_FN_FREE_MEM
    Frees memory previously allocated for user exits to use.
Parent topic: User Exits


PFI

A generic type definition for a function that returns an integer value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cobrtncode_t (*PFI)();

On Entry:

None

On Exit:

None

Function returns:

An integer

Parent topic: Support Functions


PFI_IDPES_FN_DISPLAY_TO_UTF16

Converts COBOL DISPLAY encoded strings to UTF-16 encoded strings.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDPES_FN_DISPLAY_TO_UTF16)(
                                                cobuns8_t  in_string,
                                                cobuns32_t in_len,
                                                cobuns8_t  out_string,
                                                cobuns32_t *out_len);

On Entry:

in_string | COBOL DISPLAY encoded string
in_len | Size of in_string
out_len | Maximum size of out_string, or 0 for function to return the required size of out_string

On Exit:

out_string | UTF-16 encoded string
out_len | Size of out_string, or required size if 0 specified on input, or if function returns IDPES_BUFFER_TOO_SMALL

Return codes:

0 | IDPES_SUCCESS
1 | IDPES_BUFFER_TOO_SMALL

Comments:

Used by user exits to convert COBOL DISPLAY encoded strings into UTF-16 encoded ones

Parent topic: Support Functions


PFI_IDPES_FN_UTF16_TO_DISPLAY

Converts UTF-16 encoded strings to COBOL DISPLAY encoded strings.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef cblt_rtncode (*PFI_IDPES_FN_UTF16_TO_DISPLAY)(
                                                cobuns8_t  in_string,
                                                cobuns32_t in_len,
                                                cobuns8_t  out_string,
                                                cobuns32_t *out_len);

On Entry:

in_string | UTF16 encoded string
in_len | Size of in_string
out_len | Maximum size of out_string, or 0 for function to return the required size of out_string

On Exit:

out_string | COBOL DISPLAY encoded string
out_len | Size of out_string, or required size if 0 specified on input, or if function returns IDPES_BUFFER_TOO_SMALL

Return codes:

0 | IDPES_SUCCESS
1 | IDPES_BUFFER_TOO_SMALL

Comments:

Used by user exits to convert UTF-16 encoded strings into COBOL DISPLAY encoded ones

Parent topic: Support Functions


PFV_IDPES_FN_ALLOC_MEM

Allocates memory for user exits to use.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef void *(*PFV_IDPES_FN_ALLOC_MEM)(cobuns32_t mem_size);

On Entry:

mem_size Number of bytes to allocate

On Exit:

None

Function returns:

A pointer to the allocated space, or NULL if there is insufficient memory available or an error occurs during the allocation process.

Comments:

Used by user exits to allocate memory, for example, for the creation of a replacement external data value during exit point 7, External Data Value Modification - Output Parameter. If you allocate memory using this function you should subsequently free it using the fn_free_mem support function of IDP_EXIT_SERVICE_FUNCS.

Parent topic: Support Functions


PFV_IDPES_FN_FREE_MEM

Frees memory previously allocated for user exits to use.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef void *(*PFV_IDPES_FN_FREE_MEM)(void *mem);

On Entry:

mem Memory to be freed

On Exit:

None

Function returns:

Nothing

Comments:

Used by user exits to free memory previously allocated via the fn_alloc_mem support function of IDP_EXIT_SERVICE_FUNCS.

Parent topic: Support Functions


Structures

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following structures are available:

  • IDP_EXIT_INFO
    Contains the information passed between the request handler and the user exit program.
  • IDP_EXIT_SERVICE_FUNCS
    Contains the information passed between the request handler and the user exit program.
  • REQHAND_RESPONSE
    Contains the response to the client request.
  • REQUEST_CONTEXT
    Contains information about the client request.
Parent topic: User Exits


IDP_EXIT_INFO

Contains the information passed between the request handler and the user exit program.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef struct idp_exit_info
{
    cobuns32_t             version;         Version of structure format
    cobuns32_t             flags;           Reserved for future use
    cobuns32_t             data_size;       Size of data addressed by data_ptr
    cobuns32_t             ext_value_size;  Size of data addressed by ext_value
    cobuns32_t             reserved1[10];   Reserved for future use
    IDP_EXIT_SERVICE_FUNCS *funcs;          User exit support functions
    cobuns8_t              *field_name;     COBOL Linkage Section item’s name (COBOL DISPLAY encoded)
    void                   *data_ptr;       Internal data value associated with field_name
    cobuns8_t              *ext_param_name; External parameter name (COBOL DISPLAY encoded)
    cobuns8_t              *ext_value;      External data value associated with field_name (UTF-16 encoded)
    REQUEST_CONTEXT        *request_cxt;    Request context
    REQHAND_RESPONSE       *response;       Response details
    void                   *exit_data;      User exit-specific data
    void                   *reserved2[10];  Reserved for future use
}IDP_EXIT_INFO;
Parent topic: Structures


IDP_EXIT_SERVICE_FUNCS

Contains the information passed between the request handler and the user exit program.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef struct idp_exit_service_funcs
{
    cobuns32_t                    version;         Version of structure format
    cobuns32_t                    reserved;        Reserved for future use
    PFV_IDPES_FN_ALLOC_MEM        fn_alloc_mem;    Function to allocate memory
    PFV_IDPES_FN_FREE_MEM         fn_free_mem;     Function to free memory allocated by fn_alloc_mem
    PFI_IDPES_FN_DISPLAY_TO_UTF16 fn_disp_to_utf16 Function to convert from a COBOL DISPLAY encoded format to a UTF-16 encoded format
    PFI_IDPES_FN_UTF16_TO_DISPLAY fn_disp_to_utf16 Function to convert from a UTF-16 encoded format to a COBOL DISPLAY encoded format
    PFI                           fn_reserved[10]; Reserved for future use
} IDP_EXIT_SERVICE_FUNCS;
Parent topic: Structures


REQHAND_RESPONSE

Contains the response to the client request.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef struct reqhand_response
{
    cobuns32_t version;       Version of structure format
    cobuns32_t response_len;  Length of response buffer
    cobuns32_t flags;         Control flags
    cobuns32_t response_type; Server response type
    void       *response_buf; Server response buffer
    void       *content_type; NULL terminated string (HTTP)
}REQHAND_RESPONSE;
Parent topic: Structures


REQUEST_CONTEXT

Contains information about the client request.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef struct request_context
{
    cobuns32_t            version;            Version of structure format
    cobuns32_t            handler_id;         ID of request handler being used to process the request
    cobuns32_t            request_len;        Length of request buffer
    cobuns32_t            argc;               Parameter count of loaded service
    cobrtncode_t          return_code;        Service’s return code, or run-time error error generated by service
    cobuns32_t            service_type;       Type of service request
    cobuns32_t            accept_buf_len;     Length of data in accept_buf
    cobuns32_t            display_buf_len;    Length of data in display_buf
    cobuns32_t            cmd_line_len;       Length of data in cmd_line
    cobuns32_t            flags;              Request context control flags
    cobuns32_t            reserved1[11];      Reserved for future use
    REQHAND_SERVICE_FUNCS *funcs;             Request handler support functions
    void                  *request_buf;       Request buffer
    void                  **protocol_attrs;   An array of pointers to protocol-specific attributes
    cobuns8_t             **argv;             Parameter list of loaded service
    void                  *handler_data;      Request handler-specific data
    cobuns8_t             *reserved1a;        Reserved for future use
    cobuns8_t             *service_name;      Name of loaded service
    cobuns8_t             *pgm_name;          Name of the main program associated with the service
    cobuns8_t             *epoint_name;       Name of entry point of the program to invoke
    void                  *idt;               Interface definition for service; the interpretation of the memory addressed by this field is request handler-specific
    cobuns8_t             *accept_buf;        Data to be used for ANSI ACCEPT statements
    cobuns8_t             *display_buf;       Concatenation of strings output by ANSI DISPLAY statements
    cobuns8_t             *cmd_line;          String to be used to resolve ACCEPT FROM COMMAND-LINE
    cobuns8_t             *rts_err_str;       Run-time error message text
    void                  *reserved2[9];      Reserved for future use
} REQUEST_CONTEXT;
Parent topic: Structures


Enterprise Server Security

Contains information and procedures for all aspects of securing an Enterprise Server installation.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Securing an Enterprise Server Installation
  • Using the Security Audit Manager
    The topics in this section describe how to configure and use the Enterprise Server Security Audit Manager.
  • Securing Communications
    The topics in this section describe the process of using SSL and PKI certificates to secure Enterprise Server communications.
Parent topic: Enterprise Server


Securing an Enterprise Server Installation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The topics in this section describe the security features available in an Enterprise Server installation, and how you can use these features to implement a security policy.

This help also includes the context-sensitive information available from the user interface. To access the help, select Help > This Page from the left pane.

Note: The context information in this help volume is the most up-to-date version.
  • Architecture and Overview
  • Configuring Enterprise Server Security
  • Configuring External Security Facility (ESF) from the Command Line
  • Using the MFDS Internal Security Module
  • Configuring Operating System Security: osesm
  • Configuring Security Using OpenLDAP
  • Examples
  • Managing an LDAP from the Enterprise Server UI
  • Migrating from Enterprise Server Early Versions
  • Security Reference Information
  • Glossary
Parent topic: Enterprise Server Security


Architecture and Overview

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The topics in this section describe the Enterprise Server security architecture, and provide an overview of the configuration process.

  • About Securing an Enterprise Server Installation
  • Security Architecture
Parent topic: Securing an Enterprise Server Installation


Security Architecture

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Enterprise Server security architecture accommodates mainframe-style security for:

  • Migrated applications
  • The security mechanisms found in distributed systems
  • Custom solutions

This architecture allows you to configure multiple security mechanisms and repositories, so that you can separate the management of different types of resources.

Communication between clients and the server can be secured through the use of SSL.

  • System Components and Process Flows
  • About the External Security Facility (ESF)
  • About Security Managers
  • About Security Queries
  • Designing the Security Policy
Parent topic: Architecture and Overview


System Components and Process Flows

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When a user attempts to access an Enterprise Server feature or application, or when an application attempts to access a controlled resource, Enterprise Server's External Security Facility (ESF) submits a security query to the appropriate ESMs to authenticate or authorize the action.

The illustration below shows the components involved in securing an installation, and the communications between each.

  • When they log on to a system, Enterprise Server administrators are authenticated against any security managers that are configured for the Directory Server. Access to Enterprise Server configuration is denied unless the authentication is successful.
  • When an Enterprise Servers accesses a resource, for example programs or databases, the request is authenticated against the security managers configured for the Enterprise Server. Access to the resource is denied unless the authentication is successful.
  • Security managers can use LDAP repositories to verify authentication requests.

Parent topic: Security Architecture


About the External Security Facility (ESF)

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The ESF operates for both Enterprise Server and Directory Server access.

The ESF relays application and resource access authorization request queries to the security manager or Managers. It is responsible for:

  • Loading and invoking security managers
  • Sending security queries to the security managers
  • Managing a cache of the modules and security access query results
  • maintaining configuration information for itself and the security managers

The ESF performs security checks by making API calls to the ESMs, and processing the result that is returned. You can use this API to develop your own security managers. You can then use these security managers to process authentication requests, and allow or deny access as appropriate. A security manager can be anything that can process ESF API calls.

The External Security Facility API documentation is available, in doxygen format, on the Micro Focus Supportline website's Examples and Utilities page.

  • Follow this link to the Examples and Utilities page:

    Micro Focus Supportline Examples and Utilities page

  • Follow this link to the External Security Facility API documentation, which contains information on how to configure your ESF to work with any ESMs that are deployed. The API also contains error message and return code explanations:

    External Security Facility Manager API

If no security manager recognizes a user, that is each security manager returns unknown, you can configure a default response.

Parent topic: Security Architecture


About Security Managers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Security managers process the security queries generated by the ESF, and return either an allow, deny or unknown status. You can configure multiple security managers in an installation;'s security manager pool. From the pool, you can create a default list of the security managers to use, and lists for individual Enterprise Servers.

Note: Security managers are sometimes refered to as External Security Managers, or ESMs.

The ESF sends security queries to the security managers in the order in which they are configured in the list.

You configure Enterprise Server to:

  • Authorize access when the first security manager authenticates it.
  • Authorize access only when all security managers authenticates it.
  • Authorize or block access requests that return an unknown status.

Enterprise Server includes the following security managers that you can configure and use:

  • osesm

    This security manager provides access to the Windows operating system's user configuration. You can use it to authenticate Windows users, determine a user's access level and apply permissions accordingly.

  • mldap_esm

    This security manager allows you to integrate your Enterprise Server security with an LDAP. You can use mldap_esm with both Microsoft Active Directory, and other LDAPs, for example OpenLDAP. With mldap_esm, you can implement access control for users, and for the resources and files that an application uses.

  • MFDS Internal Security

    Directory Server security can be implemented hrough the MFDS internal security manager. This security manager is used for Directory Server when no other security manager is present in its security manager list. It allows you to define users and groups, and restrict access to Enterprise Server administration functions.

  • CASESM

    This allows you to use any security configurations from software releases prior to release 5, that uses the current architecture.

In addition to the above, a security managers can be anything that can process the API security queries that the ESF generates, and can return results to the ESF. You can develop a security manager to suit your requirements. A security manager could be a database, a directory, or an operating system mechanism

Parent topic: Security Architecture


About Security Queries

Restriction: This topic applies only when the Enterprise Server feature is enabled.

During applications processing and the running of the Directory Server, Enterprise Server submits security queries to the External Security Facility (ESF), to verify that a user or system action is authorized. The ESF generates the appropriate API call and forwards this request to each configured security manager in turn.

The most common security queries are:

  • Authenticating user credentials, for example when the user signs on.
  • Checking that a user has the appropriate authorization to perform a particular task on a particular resource

A successful verify query establishes a security context (such as a session logon) within which further operations are performed. If the user or application performs subsequent operations outside this context, further authorization calls are made to check that he or she has appropriate authorization.

The verify query is used only by MF Directory Server. It implements more modern discretionary access controls (DACs). Permissions are separate from one another. For example, a user can have write access but not read access to a resource.

Parent topic: Security Architecture


Designing the Security Policy

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The design and introduction of security policy requires careful planning to ensure that the measures adopted are appropriate to the systems being used. Such considerations are beyond the scope of this documentation. This topic gives a brief overview of the steps involved in using the Security Facility to control user authentication and authorization, and resource access control.

  1. Before you can use the Security Facility, you must decide which external security managers you are going to use and, if you plan to use multiple security managers, how you want to divide the responsibilities between them. Most installations use a single external security manager.
  2. Having done this you must define, within the repositories used by those managers, the users, resources and rules that you require. This may involve migration of user and resource details from legacy Directory Server and Enterprise Server security definitions, and in the case of LDAP repositories used with the MLDAP ESM Module, modifications to the schema to support the security information.
  3. The next step is to specify within Directory Server the security managers, the ESM Modules that will be used to connect to them, and the associated configuration information. In doing this you create a pool of security manager definitions from which you can choose the ones that you require for particular enterprise servers.
  4. At this point, you can begin to define security configuration options. You can have different configuration options for individual enterprise servers, and for Directory Server. You can also have a default configuration that applies to any enterprise server that does not have its own configuration.
  5. The configuration options include an ordered list of references to the security managers that you will use. Hence, as with the other options, you can use different lists for Directory Server and individual enterprise servers, and you can have a default list used by multiple servers.

    The order of the managers on the list determines the order in which they are queried when handling a security request, and this may, depending on other configuration options, affect the result of a query.

    You can now add the appropriate security managers from the security manager pool to the list that you are using.

Parent topic: Security Architecture


Configuring Enterprise Server Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You configure security using the Enterprise Server Administration user interface. You can use this interface to configure installation-wide security configurations, and to configure security for each enterprise server in the installation. This section details the tasks required to do this.

  • Security Configuration Stages
  • Adding a Security Manager to the Pool
  • Enabling a Security Manager
  • Defining a Security Manager List
  • Setting MF Directory Server Security Configuration
  • Customizing the Security Settings for an Enterprise Server Instance
  • Implementing Security Manager Changes
Parent topic: Securing an Enterprise Server Installation
Related concepts
About the External Security Facility (ESF)


Security Configuration Stages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Configuring the security managers to use involves the following stages:

  1. Add the security managers that you plan to use to the pool, so that they are available for use in your configurations.
  2. Define the list of the security managers to use with Enterprise Server instances, and the order in which they are used.

    You can then use this configuration with multiple Enterprise Server instances

  3. Repeat the previous step to define the security configuration for the Micro Focus directory server.
    Note: To avoid issues with resource access, it is recommended that you use the same configuration for Micro Focus directory server and the enterprise server instances that it manages.
  4. Customize the security configuration for each enterprise server that requires it.
  5. Update security managers as required, and implement the changes.
Parent topic: Configuring Enterprise Server Security


Adding a Security Manager to the Pool

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before you can use an External Security Manager (ESM) in your configuration, either in the default security configuration or to configure individual enterprise servers, you need to make it available by adding it to the MFDS security manager pool.

Once it is in the pool, you can configure it and set it to verify access.

  • To Add or Remove a Security Manager in the Pool
  • To Edit a Security Manager's Properties
Parent topic: Configuring Enterprise Server Security


To Add or Remove a Security Manager in the Pool

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Security .
  2. Click the Security Managers tab, and click Add.
  3. Specify the details of the ESM to add. The minimum information required is a unique name with which to identify the definition, and the name of the external security manager module that will be used to pass security queries to the relevant external security manager. At the left of the screen, select the Help > This Page option for detailed information on the options.
  4. Click Add.

    The ESM is added to the pool and is available for use in your configurations.

To remove an ESM from the pool, select it and click Remove.
Parent topic: Adding a Security Manager to the Pool
Related tasks
To Configure a Security Manager's Environment
Related information
To Edit a Security Manager's Properties


To Edit a Security Manager's Properties

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Once you have added a security manager to the pool, you can edit its properties.

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure , click Security .
  2. Click the Security Managers tab, and in the list, select the security manager to edit.
  3. Click Edit.
  4. Specify the details of the security manager.
    Name

    Specify the name used to identify the security manager.

    Module

    Specify the module used to access an external security manager or to implement the security rules. If you specify it with a relative path (which includes no path) it is relative to $COBDIR/etc.

    Connection Path

    If the module requires a connection string that tells it how to connect to the external security manager, specify it here.

    The information supplied in the string and its format depend on the module that you are using. For details, please see the documentation supplied with the module.

    Authorized ID and Password

    If the module requires credentials to connect to the external security manager, specify them here.

    As with the connection path, the content and format of these fields depend on the module that you are using. For details, please see the documentation supplied with the module.

    Enabled

    Check this to enable this security manager. If it is disabled, it will be ignored by Directory Server and those enterprise servers that reference it.

    Cache limit

    If the module has a configurable cache for holding responses from the security manager, enter its maximum size in kilobytes here.

    Cache TTL

    If the module has a configurable cache for holding responses from the security manager, enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be requeried from the security manager.

    Note: Enterprise Server and Directory Server also have their own configurable caches for security information. These are checked before submitting queries to the security manager module.
    Description

    Specify a description of the security manager.

    Configuration information

    Specify any additional configuration settings that the module requires.

    Properties

    Click this to access pages for the management of users, groups and resources controlled by this security manager.

    Important: You will only be able to manage users, groups and resources where the security manager is on the priority list used by Directory Server. That is:
    • if Directory Server uses the Default ES Security configuration, the security manager must be on the Default ES Security manager list
    • if Directory Server uses its own configuration options, the security manager must be on the Directory Server's own security manager list

    In addition, the ESM module and the external security manager to which it connects must also support user, group and resource administration via the Security Facility.

  5. Click OK to save the changes and return to the Security Managers screen. Alternatively, click Apply to save the changes and remain on the current screen.
Parent topic: Adding a Security Manager to the Pool
Related tasks
To Configure a Security Manager's Environment
To Add or Remove a Security Manager in the Pool


Enabling a Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A security manager must be enabled before it can be used to manage securit. If a security manage is disabled, it is ignored by Micro Focus Directory Server and by all enterprise servers instances.

To disable the security manager for Micro Focus Directory Server only, or for a particular enterprise server in your installation, you must remove it from the relevant security manager list.

  • To Enable or Disable a Security Manager
Parent topic: Configuring Enterprise Server Security


To Enable or Disable a Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Security.
  2. Click Security Managers.
  3. Select the security manager to enable or disable, and click Edit.
  4. Check or un-check Enabled, and click OK.
    Note:

    This globally disables the security manager, so that it is ignored by Directory Server and by all enterprise servers. If you only wish to disable the security manager for Micro FocusDirectory Server or for a particular enterprise server, you must remove it from the relevant security manager list.

Parent topic: Enabling a Security Manager


Defining a Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Once you have added security managers to the pool, you can create a default list of the security managers to use, and select to enable or disable each. If you disable a security manager, it is not used in the authorization process, even when it appears in the list of security managers to apply.

This list is used by default for each new Enterprise Server instance that you create.

  • To Add a Security Manager to the Default ES Security Manager List
  • To Set Default Enterprise Server Security Configuration
Parent topic: Configuring Enterprise Server Security


To Add a Security Manager to the Default ES Security Manager List

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Default ES Security.
  3. In the Security Manager List, click Add.
  4. Select the definition that you want to add to the list by clicking the relevant radio button in the Select column.
  5. Click Add .
Note:
  • You cannot add the same definition to the list more than once. You can however have more than one security manager definition that uses the same external security module in the security managers pool.
  • Where you are running MF Directory Server with Restrict administration access set, and you make a change to the security manager list that it uses, you are challenged to supply:
    1. a set of credentials that are valid with the configuration prior to the changes being applied

      and

    2. a set of credentials that will be valid with the configuration after the changes are applied. This is to ensure that you can still access the MF Directory Server screens.

    If appropriate credentials are not supplied or are not valid, the changes will not be applied.

Parent topic: Defining a Security Manager List


To Set Default Enterprise Server Security Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can create a list of security managers to use as a default. Enterprise servers can use this as the default configuration. You must have added security managers to the pool before they can be configured in the default list.

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Security .
  2. Click the Default ES Security tab.

    The default security manager list is displayed.

  3. Select the security manager, and use the Up and Down arrows at the right of the list to position the security manager where you want it.

    When performing security checks, Enterprise Server validates against the security managers in the order in which they appear in the list.

  4. Complete the rest of the configurations on the screen.

    At the left of the screen, select the Help > This Page option for detailed information on the options.

Parent topic: Defining a Security Manager List


Setting MF Directory Server Security Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can configure the security configuration for the directory server. You can select to use the default MFDS Internal Security or you can configure security managers to validate against.

Note:
  • It is best to configure MFDS to use the default security configuration. If you do not do this, the enterprise server instance may not start because the Windows user account configured for starting ES is not known to the default MFDS security configuration.
  • The default MFDS Internal Security can only be used by itself. If you use this, you cannot configure any other security managers.
  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Security.
  2. Check the Restrict administration access check box.
    This sets that security checks are applied to the directory server.
    Note: When you check this option, a login screen is displayed when you log on or change configurations. The user details you enter are verified against the security configurations.
  3. In the lower half of the screen under Security Manager List, click Change to display a list of the security managers configured.
  4. Select the security manager to add, and click Add.

    The security manager is added to the MFDS list.

  5. Use the Up and Down arrows at the right of the list to position the security manager where you want it.

    When performing security checks, Enterprise Server validates against the security managers in the order in which they appear in the list.

  6. Complete the rest of the configurations on the screen.

    At the left of the screen, select the Help > This Page option for detailed information on the options.

  7. Click OK or Apply to apply your configurations.
  • To Set the MF Directory Server Security Configuration
Parent topic: Configuring Enterprise Server Security


To Set the MF Directory Server Security Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Configure MF Directory Server to use the same security configuration. If you do not do this, the enterprise server may not start because the Windows user account configured for starting ES is not known to the default MF Directory Server security configuration. If you don't want to change the MFDS security configuration now, you can add that user to MF Directory Server directly by editing the MFDS Internal Security security manager and clicking on Properties.

To use the same security configuration for Enterprise Server instances and MF Directory Server:

  1. Return to the MF Directory Server Security Options page if necessary, and select the MF Directory Server tab.
  2. Check the Use default ES Security Manager List checkbox.
  3. Click Apply. The MF Directory Server tab should now show the same security manager(s) as Default ES Security.
Parent topic: Setting MF Directory Server Security Configuration


Customizing the Security Settings for an Enterprise Server Instance

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For each enterprise server, you can use the default security manager configuration, or you can configure the security managers to use for the particular server.

  • To Set Security Configuration Options for an Enterprise Server
Parent topic: Configuring Enterprise Server Security


To Set Security Configuration Options for an Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For each enterprise server, you can use the default ESM configuration, or you can configure the ESMs to use for the particular server.

  1. From the Enterprise Server Administration home page, click Edit for the relevant enterprise server.
  2. Click the Security tab.
  3. To use the default set of configuration settings, check Use default security configuration.
  4. To use a non-default configuration, add the ESMs to use in the Security Manager List area at the bottom of the screen.
  5. Use the Up and Down arrows at the right of the list to position the ESM where you want it.

    When performing security checks, Enterprise Server validates against the ESMs in the order in which they appear in the list.

  6. Complete the rest of the configurations on the screen.

    At the left of the screen, select the Help > This Page option for detailed information on the options.

Parent topic: Customizing the Security Settings for an Enterprise Server Instance


Implementing Security Manager Changes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you are using an external security manager and you make changes to the security information (such as adding a user or changing group membership), there are two ways in which you can notify Enterprise Server so that it uses the updated information:

  • The Enterprise Server Administration interface
  • The esfupdate utility
  • To Update using the Enterprise Server Administration Interface
  • To Update Security Manager Changes Using esfupdate
Parent topic: Configuring Enterprise Server Security


To Update using the Enterprise Server Administration Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To use the Enterprise Server Administration Interface to update a server instance with changes to a security manager:

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure , click Security .
  2. Click the Security Managers tab.
  3. Below the list of configured security managers, click Update Allon the Security Manager Pool page.

    This retrieves the latest security information from the external security manager.

Use the following steps to update the security managers used by the Directory Server:

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure , click Security .
  2. Click the MF Directory Server tab.
  3. Check the Update when external Security Manager properties change check box.
Parent topic: Implementing Security Manager Changes


To Update Security Manager Changes Using esfupdate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you are using an external Security Manager and changes are made to the security information (such as adding a user or changing group membership), there are two ways in which you can notify Enterprise Server so that it uses the updated information:

  • The Enterprise Server Administration interface
  • The esfupdate utility

This topic describes the steps required to use the esfupdate utility.

The syntax of the esfupdate utility is as follows:

esfupdate [options]update-type[entity-name]
Options
A series of actions to perform. Possible values are:
Switch | Action | Meaning
-a | action | The update action to perform. One of "add", "delete", "modify" or "other". The default is "modify".
-u | user | The username for binding to Directory Server.
-p | password | The password for binding to Directory Server.
-m | host[:port] | The location of Directory Server. The default is localhost:86.
-r | server | The name of the server(s) to update. This can include wildcards.
-M | Updates the Directory Server.
-v | Displays version information and exit.
-h | Displays syntax information and exit.
update-type
One of "user", "group", "resource", "users", "groups", "resources", or "all".
entity-name
Must be supplied if update-type is "user", "group" or "resource". Otherwise omitted.

Comments

If user and password are not supplied, esfupdate attempts to bind to Directory Server anonymously.

If user is supplied but not password, you will be prompted for it.

If neither -M nor -r are specified, update notifications are sent to Directory Server and all running servers.

The example below notifies the Directory Server and any running enterprise servers that the user SAFU has been modified. This could mean that it has been added to (or removed from) a group. It will bind to Directory Server as the "SYSAD" user.

esfupdate -u CN=SYSAD -p SYSAD user SAFU
Parent topic: Implementing Security Manager Changes


Configuring External Security Facility (ESF) from the Command Line

Restriction: This topic applies only when the Enterprise Server feature is enabled.

esfadmin is a command-line utility that calls the ESF Admin API to request administrative actions against ESMs. It is a part of Visual COBOL and COBOL Server, and can be found in the $COBDIR\binand \bin64 directories.

One advantage of esfadmin is that it can be used to perform batch updates to an ESM, typically as part of a script. Another is that you supply all its configuration information on the command line, so you do not have to configure your MLDAP security manager in MFDS with an LDAP administrative user ID.

  • About the esfadmin Command
  • esfadmin Sub-commands
Parent topic: Securing an Enterprise Server Installation


About the esfadmin Command

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The esfadmin command line includes options, a subcommand, and one or more parameters.This section discusses subcommands and parameters.

Each subcommand is a single word, telling esfadmin what task you want to perform. Parameters are name and value pairs in the form name=value. If the value contains spaces or other characters that are significant to the command processor or shell you’re using, you’ll need to quote or escape them. Subcommands and parameter names are case-insensitive, but parameter values may be case-sensitive, depending on the parameter and the ESMs that process the request.

For each subcommand, one or more parameters identifies the object (user, group, resource class, or resource access control definition) you’re operating on. These parameters are required. Other parameters set attributes of that object; they are optional in most cases. Note that some ESMs may require certain parameters be set even if ESF doesn’t. For example, the standard LDAP schema supplied by Micro Focus requires that resource objects have a value for the microfocus-MFDS-Resource-class attribute (even though it’s not used—this is for historical reasons), which is set by the “class” parameter when using esfadmin, so if you try to add a resource object without specifying class=somevalue you will get an error. These requirements are noted below.

The UID attribute is a special case. It is required by the LDAP schema, but if you do not supply one for an ADD operation, the MLDAP ESM Module will generate one for you.

Most of the subcommands have the same form: ADD, ALT (alter), DEL (delete), or LIST, followed by an object type: USER, GROUP, CLASS, or RESOURCE. There are also SETPASSWORD and SETOPTIONS commands. ADD and ALT commands are described in the same topic, since they use the same parameters.

The LISTx commands list all matching objects (see the LISTUSER topic for an example of using a pattern with wildcards for a list command) and their attributes. The SETPASSWORD command is used to reset a user’s password. The SETOPTIONS command is not currently used.

  • esfadmin Command Syntax
  • esfadmin Usage Notes
  • Setting User Passwords with esfadmin
Parent topic: Configuring External Security Facility (ESF) from the Command Line
Related reference
esfadmin Command Syntax


esfadmin Command Syntax

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

esfadmin [options] subcmd [keyword=value | keyword]...

Used to update the security definitions in active External Security Managers. It calls the Enterprise Server External Security Facility (ESF) to submit requests.

Parameters:

The options are:

-a | Do not audit. By default, esfadmin sends audit information for each request to the ESF Audit Facility.
-cconfig file Specifies the name of a configuration file for the MLDAP ESM Module. This is a text file, in the same format as the "Configuration Information" area in the Security Manager definition.

Usage: esfadmin -cldap-config.txt where ldap-config.txt contains:

[LDAP]
base=CN=Micro Focus,
CN=Program Data,
DC=mycorp,DC=com
-uESF user A valid ES account that will be used to sign on to the ESF. The default is: SYSAD

Usage:

esfadmin -uSYSAD

-pESF password. | The associated password. The default is: SYSAD
-UESM user A valid username for the External Security Manager; for example, with MLDAP, a user account with appropriate access to the LDAP repository.

If this is not supplied, then for commands other than the LIST commands, esfadmin will prompt for the ESM username. (For LIST commands, esfadmin will let the ESM module use its default credentials.

-PESM password The associated password.

If this is not supplied, then for commands other than the LIST commands, esfadmin will prompt for a password.

-Sserver URL Specifies the connection path for the LDAP server.

Usage:

esfadmin -S ldap://adhost

The sub commands are:

ADDUSER, ALTUSER, DELUSER, LISTUSER
ADDGROUP, ALTGROUP, DELGROUP, LISTGROUP
ADDCLASS, ALTCLASS, DELCLASS, LISTCLASS
ADDRESOURCE, ALTRESOURCE, DELRESOURCE, LISTRESOURCE
SETPASSWORD, SETOPTIONS

Comments:

The subcommand specifies the function to be performed. Each function requires one or more parameters. Parameters consist of stand-alone keywords and keyword-value pairs. Keyword-value pairs should be entered with no spaces between the keyword, the equal sign, and the value. Values that contain spaces or other special characters should be quoted, as required by the shell.

Parent topic: About the esfadmin Command
Related concepts
esfadmin Usage Notes
About the esfadmin Command
esfadmin Sub-commands
Related information
Setting User Passwords with esfadmin


esfadmin Usage Notes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Note the following points when using esfadmin:

  • You cannot move or rename an object in the security manager because you cannot specify the parameter once to identify it, and then again to give it a new name. You must use ADDx to create the new one, and then DELx to delete the old one. The ALTx commands will let you change the other parameters of an object, for the most part.
  • You can't change a resource's class by changing its CLASS attribute. That attribute exists (and must have a value), but that's a historical vestige. To change a resource's class, you have to create a new resource of the same name under the new class using ADDRESOURCE, and then delete the old one.
  • LISTUSER shows a user's group memberships, for convenience, but that's not actually an attribute of a user. So you can't use ALTUSER to change what groups a user belongs to (except for the user’s default group). You have to use ALTGROUP to change a group to add or delete a user from it.
  • LISTRESOURCE can only list resources from a single class. To list all resource definitions matching a certain pattern, you must use one LISTRESOURCE command per resource class.
  • When you change a group member list with ALTGROUP, you completely rewrite it. Be careful to ensure that only one administrator is changing a group’s membership at a time, or changes could be lost.
  • To change a resource's access control list (ACL), you list the ACEs as the value of the ACL parameter, separated by semicolons or newlines. For example:

    esfadmin ... ALTRESOURCE ...

    ACL="allow:SYSADM group:read;allow:CICSUSER:read"

    This has the same issue as updating group membership—it replaces the entire ACL, so make sure you have all the ACEs you want in the string, and watch out for races if multiple people might be making updates at the same time.

Parent topic: About the esfadmin Command
Related reference
esfadmin Command Syntax
ADDGROUP and ALTGROUP
ADDCLASS and ALTCLASS
ADDRESOURCE and ALTRESOURCE
ADDUSER and ALTUSER
DELCLASS
DELGROUP
DELRESOURCE
DELUSER
LISTCLASS
LISTGROUP
LISTRESOURCE
LISTUSER


Setting User Passwords with esfadmin

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you edit a user's password (the microfocus-MFDS-User-Pwd attribute) directly in the LDAP repository, using a tool such as ADSIEdit, you can only set a literal password value. This is often not satisfactory because the password can be seen by anyone who can read the repository.

If you have enabled MFDS administration of the LDAP repository, you can use MFDS to change a user's password. To do this, go to the MFDS security options, view the list of Security Managers, select the MLDAP manager, click the Properties button, edit the user, and set a new password. See the MFDS documentation for more information.

Another alternative is to use the esfadmin utility.

To set a password using the esfadmin command, you will need a valid ES username and password (not necessarily the user whose password you're setting), and an LDAP username and password for an account with write access to the user's record in the repository. esfadmin has to sign on to ESF before it can perform an admin request, which is why you need an ES username / password.

You set a password using the setpassword option:

esfadmin [options] setpassword user=username password=new-password

esfadmin will prompt for the LDAP user ID and password. (The user ID is usually specified as an LDAP DN, eg CN=admin,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local; or as a Windows username with domain, eg domain\admin.) You can also specify these on the command line using the -U and -P options (note these must be uppercase-U and uppercase-P).

By default esfadmin uses "SYSAD", one of the default accounts created during setup, for the ES username and password it uses to sign on to ESF. You can supply a different username and password with the -u and -p (both lowercase) options.

Parent topic: About the esfadmin Command
Related reference
esfadmin Command Syntax


esfadmin Sub-commands

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The esfadmin command can use the following sub-commands:

  • ADDCLASS and ALTCLASS
  • ADDGROUP and ALTGROUP
  • ADDRESOURCE and ALTRESOURCE
  • ADDUSER and ALTUSER
  • DELCLASS
  • DELGROUP
  • DELUSER
  • DELRESOURCE
  • LISTCLASS
  • LISTGROUP
  • LISTRESOURCE
  • LISTUSER
  • SETOPTIONS
  • SETPASSWORD
Parent topic: Configuring External Security Facility (ESF) from the Command Line
Related reference
esfadmin Command Syntax


ADDCLASS and ALTCLASS

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Add a new class/modify an existing class.

Required parameters

CLASS=name
Name of the resource class

Optional parameters

DESC=description
Description text.
Note: Classes are just standard LDAP container objects, so all they have is a name and an optional description.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


ADDGROUP and ALTGROUP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Add a new group/modify an existing group.

Required parameters

GROUP=name
Name of the group.

Optional parameters

MEMBERS=user list
List of users, separated by semicolons. See the note regarding setting group membership in the esfadmin Usage Notes topic.
DESC=description
Description text.
CUSTOM=string
Custom text (not used by Micro Focus).
UID=string
Unique ID (is automatically generated if not supplied with the request).
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


ADDRESOURCE and ALTRESOURCE

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Add a new resource/modify an existing resource.

Required parameters

RESOURCE=name
Name of the resource.
CLASS=name
Name of its class. Required, but not used by Micro Focus.

Optional parameters

ACL=list of ACEs
ACEs separated by semicolons.
DESC=description
Description text.
CUSTOM=string
Custom text (not used by Micro Focus).
UID=string
Unique ID. If not supplied, one is generated automatically.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


ADDUSER and ALTUSER

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Add a new user/modify an existing user.

Required parameters

USER=username
Name of the user to add or change.

Required by standard MF LDAP schema for ADDUSER:

ALLOW=TRUE|FALSE
Whether user can sign on.
Note: The TRUE|FALSE values must be in block capitals as shown.

Optional:

NAME=display name
User’s display name.
DESC=description
Description text.
GROUP=group name
Default group.
EXPIRES=yyyymmdd
Account expiration date.

The date format depends on the ESM in use. With the MLDAP ESM, you need to use the date format required by the LDAP server. You need to check to determine what this format is.

For example:
EXPIRES=YYYYMMDDHHMMSS.0Z
where 0Z represents the GMT zone.
PASSWORD=string
Password (will be stored as MF-MD5 salted hash).
PASSEXP=<date>

Password expiration date.

The date format depends on the ESM in use. With the MLDAP ESM, you need to use the date format required by the LDAP server. You need to check to determine what this format is.

For example:
PASSEXP=YYYYMMDDHHMMSS.0Z
where 0Z represents the GMT zone.
PASSCHG=TRUE|FALSE
Whether user must change password.
Note: The TRUE|FALSE values must be in block capitals as shown.
GETTOKEN=none|self|any
Permission to create passtokens.
USETOKEN=none|self|any
Permission to use passtokens.
CUSTOM=string
Custom text (not used by Micro Focus).
UID=string
Unique ID. If not supplied, one is generated automatically.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


DELCLASS

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Delete a class.

Required parameters

CLASS=name
Name of the resource class to delete.
Warning: All resource access control definitions in this class will also be deleted!
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


DELGROUP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Delete a group.

Required parameters

GROUP=name
Name of the group to delete.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


DELUSER

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Required parameters

USER=name
Name of the user to delete.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


DELRESOURCE

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Delete a resource.

Required parameters

RESOURCE=name
Name of the resource to delete.
CLASS=name
Name of its class.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTCLASS

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

List the classes.

Required parameters

CLASS=pattern
Pattern name, optionally with “*” wildcards.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTGROUP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

List the groups.

Required parameters

GROUP=pattern
Group name, optionally with “*” wildcards.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTRESOURCE

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

List the resources.

Required parameters

RESOURCE=pattern
Resource name, optionally with “*” wildcards.
CLASS=name
Name of class to search.
Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


LISTUSER

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

List the users.

Required parameters

USER=pattern
User name, optionally with “*” wildcards.

Example

esfadmin listuser user="A*"

Lists all users with names beginning with “A”.

Parent topic: esfadmin Sub-commands
Related concepts
esfadmin Usage Notes


SETOPTIONS

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Not currently in use.

Parent topic: esfadmin Sub-commands


SETPASSWORD

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Description

Sets or resets a user password.

Required parameters

USER=name
Name of user whose password is being reset.
PASSWORD=string
New password (will be stored as MF-MD5 salted hash).
Parent topic: esfadmin Sub-commands


Using the MFDS Internal Security Module

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use the MFDS Internal Security Module to secure the directory server or enterprise servers.

Note: This module cannot be used with any other security managers. It must be the only module configured.

With the the MFDS Internal Security Module, the ability to view, and to alter, objects and schema settings within Directory Server is controlled through a system of user accounts, user groups and permissions.

With this module in place, Enterprise Server administrators must log on. The features available to login IDs are controlled by permissions. You grant permissions to a user group. The users within that group can then perform the actions governed by those permissions.

  • Working with Users, Groups and Resources
  • Application Access and Administration Access
  • Understanding Users and Groups
  • Understanding Permissions
  • Managing Users and Groups
Parent topic: Securing an Enterprise Server Installation


Working with Users, Groups and Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: Typically, you can maintain user, group and resource information for the MFDS Internal Security manager only. If you use an external security manager, you would normally use the updating functionality associated with the particular LDAP that you are using to maintain this information. Check the documentation provided with your ESM module for details.

The property screens for the MFDS Internal Security manager can be used for adding, editing and deleting user, group and resource definitions held in this manager, and for specifying resource permissions.

In addition to the conditions listed above, the MFDS Internal Security manager definition must be used by MF Directory Server.

In order to use these property screens, your user account must have User Administration permissions. See Resource Classes for MF Directory Server for details.

Parent topic: Using the MFDS Internal Security Module


Application Access and Administration Access

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When Directory Server is using the MFDS Internal Security Manager, any enterprise server that connects to the Directory Server to obtain or modify configuration information must supply valid user credentials. If, in addition, you have set the Restrict administration access configuration option, any user wanting to use the administrative features must provide credentials to log on. The features available to the user or application are controlled by permissions. You grant permissions to a user group. The users within that group can then perform the actions governed by those permissions.

Parent topic: Using the MFDS Internal Security Module


Understanding Users and Groups

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you connect to Enterprise Server Administration for a Directory Server that is running in restricted mode, you are presented with a summary screen. This screen shows basic details of the enterprise servers managed by the Directory Server.

Before you can perform any other actions, you must log on. To do this you require a user account. Directory Server comes with a number of preconfigured user accounts but you can create others.

When you have logged on, the features that you can use depend on the permissions granted to the user groups of which your user is a member.

Each user can be in many user groups. Again, Directory Server has several preconfigured groups and you can create others. Each of the preconfigured groups has appropriate permissions for a particular administrative task. One or more of the supplied users are assigned to each of the groups, with the exception of the System group, which is used by Micro Focus applications.

Group | Description | Preconfigured users assigned
All Users | This is the most limited group. Its default Enterprise Server permissions are set as Read only. This permission enables a user in the group to view configuration information for enterprise servers. All users are included in this group. | schemaadmin, adddelete, modify, administrator
Add/Delete This group has default Enterprise Server permissions that enable:
  • the addition and deletion of servers
  • the addition and deletion of services, listeners and packages to servers
adddelete, administrator
General Administrators | This group has default enterprise server permissions that enable all administration activities for enterprise servers. It also has permissions allowing all Directory Server administration activities with the exception of user managements. | administrator
Directory Server Administrators | This group has full permissions for the administration of the Directory Server and all enterprise servers. | schemaadmin
Modify | This group has default enterprise server permissions that enable the modification of enterprise server configuration information. | modify
System | This group is for the use of Micro Focus applications.
Parent topic: Using the MFDS Internal Security Module


Understanding Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A permission controls use of a feature of Directory Server. For example, there is a permission that governs the administration of users and groups. You grant permissions to user groups.

There are two categories of permissions:

Directory Server Administration | These govern the administration of the Directory Server repository (for example, the management of user accounts).
Server | These govern the administration of the enterprise servers that are controlled by the Directory Server.

Some permissions include others. For example, the permission to modify an enterprise server includes the permission to start and stop the server. When a permission is granted, all those that it includes are automatically granted.

  • Directory Server Permissions
  • Server Permissions
Parent topic: Using the MFDS Internal Security Module


Directory Server Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following table describes the available Directory Server permissions.

Name | Description
Save Repository | Permits saving a copy of the repository to a file system directory.
Import Repository | Permits importing data from a file system directory. Includes the following permissions: Save Repository.
Restore Repository | Permits restoring a repository from a file system directory. The process of restoring overwrites all of the information in the current repository. Includes the following permissions: Save Repository, Import Repository.
Delete Repository | Permits deletion of the entire Directory Server repository including all enterprise servers, and all users and groups. Includes the following permissions: Save Repository, Import Repository.
Change MF Directory Server options | Permits changing of Directory Server options. Includes the following permissions: Save Repository, Import Repository.
Set Server Permissions | Permits the allocation of permissions on individual enterprise servers. Includes the following permissions: Save Repository, Import Repository, Restore Repository, Delete Repository, Change MF Directory Server.
Display Directories | Permits the viewing of a list of the Directory Servers that your Directory Server can detect on the network. Includes the following permissions: Save Repository, Import Repository, Restore Repository, Delete Repository, Change MF Directory Server, Set Server Permissions.
Shutdown MF Directory Server | Permits the shutting down of the Directory Server. Includes the following permissions: Save Repository, Import Repository, Restore Repository, Delete Repository, Change MF Directory Server, Set Server Permissions.
Administer Users | Permits the management of user accounts and user groups, and the setting of permissions. Includes the following permissions: Save Repository, Import Repository, Restore Repository, Delete Repository, Change MF Directory Server, Set Server Permissions, Display Directories, Shutdown MF Directory Server.
Parent topic: Understanding Permissions


Server Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following table describes the available server permissions.

Name | Description
Read | Permits viewing of an enterprise server configuration information.
Start/Stop | Permits the starting and stopping of an enterprise server. Includes the following permissions: Read
Modify | Permits the modification of configuration information for an enterprise server. Includes the following permissions: Read, Start/Stop
Add | Permits the adding of listeners, services and packages to an enterprise server. When set as a default permission for the group, it also permits the adding of enterprise servers. Includes the following permissions: Read, Start/Stop, Modify
Delete | Permits the deletion of enterprise servers, and of listeners, services and packages from an enterprise server. Includes the following permissions: Read, Start/Stop, Modify

You can set default server permissions for a group, but you can also override these defaults for individual enterprise servers. For example, you might have an operator group with default permissions to start and stop servers. You could override these for your test server, specifying that the operator group also has modify permission.

Note:

To permit a group to create new servers, you must set its default Add permission.

Parent topic: Understanding Permissions


Managing Users and Groups

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You use screens within Enterprise Server Administration to manage users and user groups. To do this, you must be logged on to a user account that is a member of a group with appropriate permissions. The preconfigured user, schemaadmin is suitable for this task.

  • Setting Permissions
  • Best Practice
Parent topic: Using the MFDS Internal Security Module


Setting Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You set the permissions for each group using screens within Enterprise Server Administration. To do this, you must be logged on to a user account that is a member of a group with appropriate permissions. The preconfigured user, schemaadmin is suitable for this task.

Parent topic: Managing Users and Groups


Best Practice

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Change the passwords of the preconfigured accounts at the earliest possible opportunity.

Ensure that only those users who need access have user accounts.

Ensure that users have only the permissions that they require in order to do their jobs.

Limit the number of administrative users.

Parent topic: Managing Users and Groups


Configuring Operating System Security: osesm

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The operating system security manager (osesm) lets users sign in to ESF-protected systems (ES regions and MFDS) using their operating system username and password.

Note: osesm is supported only on Windows.
  • How osesm Works
  • osesm Module Configuration
Parent topic: Securing an Enterprise Server Installation


How osesm Works

Restriction: This topic applies only when the Enterprise Server feature is enabled.

With the osesm security manager, users sign on to MFDSand/or Enterprise Server Administration using their Windows username and password.

Note: osesm only supports the Verify operation (user sign-on). It does not do any resource access control (the Auth and XAuth operations). To control access to resources for signed-on users, you will need to configure another ESM module lower in the list for that purpose.

By default osesm first tries to sign a user on locally. If that fails, it does a search in the default domain (in the domain forest, on Windows 2003 and later) and tries again in the first domain where it finds the user. You can specify a different domain to try initially in the security manager configuration.

Note: osesm is limited to the signon IDs that Windows normally allows, and therefore it cannot verify a user in a domain that is not trusted by the local system. osesm can authenticate users from any domain that is listed in the Windows sign-on dialog. It cannot authenticate signons of the form username@domain.tld: the signon screens do not support this.

osesm supports ESF Passtokens, which can be used to automatically pass credentials between MFDS and the Enterprise Server administration UI, if both the directory server and Enterprise Server are configured to use osesm.

Parent topic: Configuring Operating System Security: osesm


osesm Module Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Because osesm uses the operating system to authenticate user credentials, it doesn't have many configuration parameters. For information on the configuration fields, in the Edit Security Manager screen's left hand pane, select the Help > This Page option.

The osesm module also supports some additional configuration that can be set by editing the text in the Configuration Information area. Text in this area is organized into sections which begin with a tag in square brackets, followed by lines of the form: name=value.

Below are the various configuration sections you can configure, and the options that can be set in each section.

[Operation] section
domain=domain

Sets the default domain for checking the user's credentials. By default this is ".", which means to try to log the user on to the local system.

type=network | interactive

Sets the type of logon to use. Windows supports a number of logon types. Servers typically use the network logon to verify user credentials, as it is supposed to be faster and use less resources. However, it requires that the user has the "Use this computer over a network" right, which some user accounts may not have. Also, it does not work in some situations where the user should be able to log on, for example when a Windows XP system is trying to verify a domain user who does not have a local account. If you find users cannot log on using their correct domain usernames and passwords, try setting this to interactive, which will perform a full Windows interactive logon.

The default is network.

[Passtoken] section
enable=none | self | any

Sets the passtoken creation and use privileges:

  • none disables passtokens.
  • self allows the creation and use of self-only passtokens (users can use passtokens to transfer their credentials between the directory server and the administration user interface, for example).
  • any allows the creation of self and surrogate passtokens. This is a security risk: an attacker who learns how to forge surrogate passtokens could use them to sign on to any facility that accepts surrogate passtokens. (Currently ES does not use surrogate passtokens, but they might be used in the future for inter-region transaction routing, for example.)

The default is none. Set it to self if you want to be able to move between MFDS and ESMAC without signing on twice.

secret=string
Sets the secret data which will serve as the key for the Message Authentication Code (MAC) in ESF Passtokens generated by the ESM Module. This data prevents attackers who do not know it from forging passtokens. Note that any setting here will obviously not be secret from anyone who can read the MFDS repository. If this value is set, it must be set the same for all security domains (MFDS and ES regions) that will exchange passtokens.
secret file=path
Sets the path to a file that contains the secret data for the passtoken MAC. This is more secure than setting the secret data directly in the configuration. If SecretFile is set, any Secret directive is ignored. (If neither is set, a built-in default is used.)
duration=seconds
Sets the duration for passtokens. A token will be valid for this length of time after it's generated; after that it will be rejected. The default is 60 (one minute).
Parent topic: Configuring Operating System Security: osesm


Configuring Security Using OpenLDAP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The MLDAP ESM module mldap_esm enables the Security Facility to use an LDAP server as an external security manager. The MLDAP ESM module can communicate with a variety of LDAP servers including OpenLDAP servers. The server can operate either on the same machine as your Enterprise Server installation, or it can be remote.

The content in this section assumes that you have already installed on your server machine, OpenLDAP and the OpenLDAP server, and the Enterprise Server software that is used by your Micro Focus product.

Important: You can use the information in this section to configure LDAP types other than OpenLDAP.
  • Using an LDAP client library
  • About OpenLDAP for the Micro Focus Environment
  • Installing the Required Schema Extensions
  • Configuring the OpenLDAP server
  • Configuring mldap_esm Security Manager for an LDAP
Parent topic: Securing an Enterprise Server Installation


Using an LDAP client library

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To use an LDAP server for Enterprise Server security, or to hold Enterprise Server configuration data (also known as an MFDS repository), you must have an LDAP client library installed.

Some operating systems include one with the default installation, or as an optional package. Microsoft Windows includes Microsoft's LDAP client as part of the base OS. AIX ships with IBM Directory Server, an installable option, which includes an LDAP client. Solaris also includes an LDAP client which is usually part of the default installation. OpenLDAP packages are available for Red Hat and SuSE Linux distributions and can be installed with rpm or yum respectively.

You can also obtain the OpenLDAP sources from http://www.openldap.org/ and build the OpenLDAP client library by following the instructions there.

Parent topic: Configuring Security Using OpenLDAP


About OpenLDAP for the Micro Focus Environment

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Within the LDAP directory, you define users, user groups, resource classes, and resources, and these objects contain the attributes used to make security checks (for the Verify, Auth, and XAuth procedures). Micro Focus defines an LDAP schema for these objects and their attributes, but in many cases you can adapt an existing directory for at least part of this information, for example in order to reuse an existing repository of user information.

When it processes a security request, the module searches the configured LDAP repository for relevant rules and applies whatever it finds.

The External Security Facility API documentation is available, in doxygen format, on the Micro Focus Supportline website's Examples and Utilities page.

  • Follow this link to the Examples and Utilities page:

    Micro Focus Supportline Examples and Utilities page

  • Follow this link to the External Security Facility API documentation:

    External Security Facility Manager API

Parent topic: Configuring Security Using OpenLDAP


Installing the Required Schema Extensions

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: Before you commence this procedure, ensure that you have sufficient access, for example root access, to create files in the $COBDIR/lib directory.
  1. Make sure that the Micro Focus bin directory is in your path.
  2. Start a command prompt and go to the OpenLDAP install directory.
  3. cd to the schema directory.
  4. Generate the MFDS OpenLDAP schema by issuing the following command:
    mfds -l dc=x 2
    This creates a schema file, for example mfds_1.08.43.schema in the $COBDIR/lib directory.
  5. Now create a new file called container.schema, which must look like this
    objectclass (
       1.2.840.113556.1.3.23
       NAME 'container'
       SUP top
       STRUCTURAL
       MUST ( cn ) )
    The container objectclass is used to group collections of like objects within the LDAP server Directory Information Tree in the Micro Focus extensions.
    Note:

    It is very important that when this schema file is created, there is no trailing whitespace on any of the lines that the schema file contains.

  • Adding default MFDS users, user groups and resources
Parent topic: Configuring Security Using OpenLDAP


Adding default MFDS users, user groups and resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Create an LDIF file file containing the user, group and resource definitions by using the mfds -e command. For example:
    mfds -e "cn=Micro Focus,dc=my-domain,dc=com" "cn=Enterprise Server Users" "cn=Enterprise Server User Groups" "cn=Enterprise Server Resources" 2 "c:\program files\openldap\mfds_users.ldf"
  2. Import the generate file using ldapadd. For example:
    ldapadd -v -D "cn=Manager,dc=my-domain,dc=com" -w secret -f mfds_users.ldf
  3. Confirm the creation of the containers using ldapsearch. To dump the contents of the Micro Focus container use:
    ldapsearch -x -b "dc=my-domain,dc=com" -s sub +
Parent topic: Installing the Required Schema Extensions


Configuring the OpenLDAP server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. At the command prompt, cd to the OpenLDAP install base directory.
  2. Edit the OpenLDAP server configuration file, slapd.conf, to add the following include statements:
    include      ./schema/cosine.schema
include      ./schema/inetorgperson.schema
include      ./schema/container.schema
include      ./schema/mfds.schema

You can now start the OpenLDAP server.

  • Confirming Extension Installation
  • Creating Standard Micro Focus application containers
Parent topic: Configuring Security Using OpenLDAP


Confirming Extension Installation

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Issue the following command:
    ldapsearch -x -b "cn=subschema" -s base + > schema.txt
  2. Check the contents of the resulting file, schema.txt, to verify that there are attribute and objectClass entries that begin with "microfocus-".
Parent topic: Configuring the OpenLDAP server


Creating Standard Micro Focus application containers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before adding the standard Micro Focus containers, the initial domain context object needs to be added.

  1. Create a file called top.ldf with contents similar to those shown below.
    dn: dc=my-domain,dc=com
objectClass: dcObject
objectClass: organization
dc: my-domain
description: My domain description
o: My domain
  2. To add the domain context object use:
    ldapadd -v -D "cn=Manager,dc=my-domain,dc=com" -w secret -f top.ldf

    The successful output should look something like the following:

    add objectClass:
        dcObject
        organization
add dc:
        my-domain
add description:
        My domain description
add o:
        My domain
adding new entry "dc=my-domain,dc=com"
modify complete

You can now add the standard Micro Focus containers.

  1. Create a file called mf-containers-open.ldf, with contents as follows:
    dn: cn=Micro Focus,dc=my-domain,dc=com
cn: Micro Focus
objectClass: container

dn: cn=Enterprise Server Resources,cn=Micro Focus,dc=my-domain,dc=com
cn: Enterprise Server Resources
objectClass: container

dn: cn=Enterprise Server Users,cn=Micro Focus,dc=my-domain,dc=com
cn: Enterprise Server Users
objectClass: container

dn: cn=Enterprise Server User Groups,cn=Micro Focus,dc=my-domain,dc=com
cn: Enterprise Server User Groups
objectClass: container
  2. Create the containers by issuing the following command:
    ldapadd -v -D "cn=Manager,dc=my-domain,dc=com" -w secret -f mf-containers-open.ldf
  3. Confirm the creation of the containers by using ldapsearch to dump the contents of the Micro Focus container:
    ldapsearch -x -b "dc=my-domain,dc=com" -s sub +
Parent topic: Configuring the OpenLDAP server


Configuring mldap_esm Security Manager for an LDAP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The default mldap_esm security manager settings are designed for the simple LDAP configuration using AD LDS and the Micro Focus user class. Before the mldap_esm security manager can update the information in an LDAP server, you need to set a number of configuration options.

  • Set Connection Path to the IP address and port of the LDAP server (for example ad-host:389)
  • Set Authorized ID to the DN of a user with appropriate permissions for the LDAP repository (for example CN=Administrator,CN=users,DC=somecorp,DC=com ). This user must have at least read access to the containers for user definitions and their contents. If you want to use the MFDS administration console to change user groups and resource access rules, this ID will also need update access to those portions of the repository.
  • Set Password to the password for the user specified in Authorized ID.
  • In Configuration Information, you will need to set a number of LDAP parameters:
    [LDAP]
base=DN-suffix
user class=user class
user container=user-container
resource container=resource-container
    DN-suffix | The common part of the DN for your user container.
    user class The LDAP object class used for your users. The following options are available:
    • microfocus-MFDS-User

      This is the default setting.

    • user

      Microsoft standard users are used and you cannot add or modify users from the MFDS user interface.

    user-container | The DN of the container for user objects, without the "base" suffix, for example: CN=users
    resource-container | The DN of the container for resource access class containers (which in turn hold resource access definition objects), without the "base" suffix, for example CN=Enterprise Server Resources,CN=MF
Parent topic: Configuring Security Using OpenLDAP


Examples

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section contains examples of using LDIF to define Enterprise Server security information in Active Directory.

  • Defining a User with LDIF
  • Defining a Group with LDIF
  • Defining CAS Resources with LDIF
  • Defining Files with LDIF
Parent topic: Securing an Enterprise Server Installation


Defining a User with LDIF

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Command | Description
dn: CN=SEC01,CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=local | Identifies user SEC01
changetype: delete | Action is set to delete, the current definition for user SEC01 will be deleted
 | You must leave a blank line between actions
dn: CN=SEC01,CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=local | Identifies user SEC01
changetype: add | Action is set to add
objectClass: microfocus-MFDS-User | Object class, we are defining a User
microfocus-MFDS-UID: no | UID (Unique Identifier). use mfuid as the value
microfocus-MFDS-User-CreateToken: self | User can create a passtoken for himself. (Used for single signon, the user can sign into MFDS and credentials will be passed to ESMAC)
microfocus-MFDS-User-MTO-Priority: 0 | User priority
microfocus-MFDS-User-MTO-Timeout: 0 | User login timeout in minutes, 0 means no timeout. (Inactivity when signed on)
microfocus-MFDS-User-MTO-OperatorClass: 0 | Operator Class
microfocus-MFDS-User-DefaultGroup: PAYROLL | Default group. A user as a default group, but can be part of several groups. The default group is used if the user does not specify a group when login in
microfocus-MFDS-User-AllowLogon: TRUE | TRUE if the user can login to a terminal or ESMAC
microfocus-MFDS-User-Pwd: literal:UserPassword | User password, this can be changed by the user using ESMAC
microfocus-MFDS-User-UseToken: self | The User can be signed using a passtoken created for himself (Used for single signon)
description: User Description | User description, used for documentation purposes
Parent topic: Examples


Defining a Group with LDIF

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Command | Description
dn: cn=PAYROLL,CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=local | Identifies group PAYROLL
changetype: delete | Action is set to delete, the current definition for group PAYROLL will be deleted
 | You must leave a blank line between actions
dn: cn=PAYROLL,CN=Enterprise Server User Groups,CN=Micro Focus,CN=Program Data,DC=local | Identifies group PAYROLL
changetype: add | Action is set to add
adminDisplayName: Payroll group | Display Name
objectClass: microfocus-MFDS-Group | Object class, we are defining a Group
microfocus-MFDS-UID: no | UID (Unique Identifier). use mfuid as the value
description: People who can process Payroll | Description for the group
microfocus-MFDS-Group-Member: SEC01 | User SEC01 is part of the group
microfocus-MFDS-Group-Member: SEC02 | More than one user can be added to the group
microfocus-MFDS-Group-Member: SEC03 |
Parent topic: Examples


Defining CAS Resources with LDIF

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Command | Description
dn: CN=OPERCMDS,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies resource OPERCMDS
changetype: add | action set to add, will create the resource
objectClass: top | This is a main class
objectClass: container | will contain entities
description: Class for operator commands used by casstart/casstop/casout/casfile/cassub commands | description
 | You must leave a blank line between actions
dn: CN=casstart,CN=OPERCMDS,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the entity we want to delete
changetype: delete | action set to delete, we remove any existing definition
 | You must leave a blank line between actions
dn: CN=casstart,CN=OPERCMDS,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the entity we want to create
changetype: add | action set to add in order to create the entity
objectClass: microfocus-MFDS-Resource | We are creating a resource
microfocus-MFDS-Resource-Class: OPERCMDS | name of the class that the entity belongs to
microfocus-MFDS-Resource-ACE: allow:SYSADM group:alter | Terminology definition, we allow any one from SYSADM group to start the ES region
microfocus-MFDS-Resource-ACE: deny:*:execute | We deny all the others
microfocus-MFDS-UID: no | UID (Unique Identifier). use mfuid as the value
description: casstart command to start an ES region | description
 | You must leave a blank line between actions
dn: CN=casstop,CN=OPERCMDS,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the entity we want to delete
changetype: delete | action set to delete, we remove any existing definition
 | You must leave a blank line between actions
dn: CN=casstop,CN=OPERCMDS,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the entity we want to create
changetype: add | action set to add in order to create the entity
objectClass: microfocus-MFDS-Resource | We are creating a resource
microfocus-MFDS-Resource-Class: OPERCMDS | name of the class that the entity belongs to
microfocus-MFDS-Resource-ACE: allow:SYSADM group:alter | Terminology definition, we allow any one from SYSADM group to stop the ES region
microfocus-MFDS-Resource-ACE: deny:*:execute | We deny all the others
microfocus-MFDS-UID: no | UID (Unique Identifier). use mfuid as the value
description: casstop command to stop an ES region | description
Parent topic: Examples


Defining Files with LDIF

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Command | Description
dn: CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies resource
changetype: add | action set to add, will create the resource
objectClass: top | This is a main class
objectClass: container | will contain entities
description: Class for controlling access to datasets | Description
 | You must leave a blank line between actions
dn: CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local |
changetype: delete | action set to delete, we remove any existing definition
 | You must leave a blank line between actions
dn: CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local | Identifies the entity we want to create
changetype: add | action set to add in order to create the entity
objectClass: microfocus-MFDS-Resource | We are creating a resource
microfocus-MFDS-Resource-Class: DATASET | name of the class that the entity belongs to
microfocus-MFDS-Resource-ACE: allow:SYSADM group:update | Terminology definition, users or groups that can access the resource and their authorisation. In this case we allow any one from SYSADM group to update the file.
microfocus-MFDS-Resource-ACE: allow:SEC01:update | more than one Terminology definition can be added
microfocus-MFDS-UID: no | UID (Unique Identifier). use mfuid as the value
Parent topic: Examples


Managing an LDAP from the Enterprise Server UI

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You use the mldap_esm security manager to configure an LDAP for use with your Enterprise Server installation. You can configure a security manager so that you can use it to administer the LDAP information from the MFDS user interface. This applies to Active Directory and other LDAP implementations, for example OpenLDAP.

Note:

Typically:

  • You use your LDAP's administration and management functionality to configure and manage your LDAP.
  • You use the Enterprise Server user interface to make minor changes to LDAP configurations.
  • About Managing an LDAP
  • Changing User Passwords Stored in an LDAP
  • About Users, Groups and Resources
  • Managing User Access
  • Managing Groups
  • Assigning Resource Permissions
  • Security Configuration Screen Help
Parent topic: Securing an Enterprise Server Installation


About Managing an LDAP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use the property screens for a security manager definition that uses mldap_esm to add, edit and delete user, group and resource definitions held in the associated LDAP repository, and for specifying resource permissions.

The mldap_esm security manager binds at configuration time only to the LDAP server, using credentials supplied as part of its configuration. All the privileges that it has for that repository are determined by those credentials. Therefore, in order to manage users, groups and resources through these property screens, you will need to ensure that these credentials have sufficient permissions on the LDAP server.

Note:

The MF Directory Server user ID with which you access the property screens is not related in any way to the credentials with which the mldap_esm security manager connects to the LDAP server. For added protection, when you attempt to access the security manager property screens, MF Directory Server will switch to "Restrict administration access" mode, requiring you to enter valid MF Directory Server user credentials.

Note also that when no authorized ID and password is specified in the security manager definition, the mldap_esm security manager uses the user ID, CN=MFReader,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local (though the last two components can be changed by setting the base DN), which is the user object created for this purpose in the sample configuration, and the password "mf_rdr" to connect to the LDAP repository. Of course, as these values are well known, you should not give MFReader write permission to your LDAP repository.

Instead of storing user passwords in the LDAP repository, the Security Facility stores password verifiers, in the form of salted MD5 hashes.

Parent topic: Managing an LDAP from the Enterprise Server UI


Changing User Passwords Stored in an LDAP

Restriction: This topic applies only when the Enterprise Server feature is enabled.

There are various ways for Enterprise Server users to change passwords stored in an LDAP. The Security Facility relays these requests to the security managers that are used to verify the user. Whether or not a password change request is honoured by a security manager depends on that manager and the security manager module that is used to connect to it.

When using the mldap_esm security manager, changing a user's password involves changing an attribute of the associated user object in the LDAP repository. This in turn requires that the mldap_esm security manager has write access to the repository. However, the mldap_esm security manager does not connect to the repository with the credentials of the user requesting the password change; it uses the authorized id and password that are specified in the Edit Security Manager screen.

In order to enable the mldap_esm security manager to support the changing of user passwords, you need to modify the security manager definition to specify an authorized user ID and password that has write access to the Enterprise Server user objects within the LDAP repository. The ID and password combination that you supply should, of course, be secret. To do this:

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the definition that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. In the Authorized ID field, supply the username used to bind to the LDAP server. The format for this is server-dependent, but is usually a Distinguished Name.

    This user should have read access to the Enterprise Server user, group, and resource objects in the LDAP repository, and modify access to user definitions to support letting users change their passwords from ES.

  6. In the Password field specify the password used to bind to the LDAP server.
  7. Click OK.
Note:

When no authorized ID and password is specified in the security manager definition, the MLDAP ESM uses the user ID, CN=MFReader,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local (though the last two components can be changed by setting the base DN), which is the user object created for this purpose in the sample configuration, and the password mf_rdr to connect to the LDAP repository. Of course, as these values are well known, you should not give MFReader write permission to your LDAP repository.

Parent topic: Managing an LDAP from the Enterprise Server UI


About Users, Groups and Resources

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Each item (for example, program, file, transaction) to which access is controlled is a called a resource. A resource has a name and a class, which indicates the type of the resource. For example, each enterprise server is a resource, and all enterprise servers belong to the same resource class.

A resource name must be unique within its class. That is, you can define two or more resources with the same name, provided that they belong to different classes.

When a user requests access to a resource the security facility relays the request to the external security manager, specifying the user, the resource and the resource class. The security manager will then look for resource rules that match the resource name. The processing of a request is dependent on the external security manager.

Where your ESM module provides suitable support, as is the case with the mldap_esm module, you can use the Enterprise Server Administration screens to define users, groups, resource classes and resources (referred to as resource entities). In defining a resource entity, you are specifying a rule against which an authorization request can be matched. Depending on your ESM, the resource entity might have a full resource name, or might contain wildcards. This allows you to write a single rule to apply to multiple resources.

With the mldap_esm module, for example, each resource entity has an Access Control List (ACL) that specifies access rights for that resource. Each entry in an ACL is referred to as an Access Control Entry, or ACE. These entries identify a user or group, and what permissions are to be granted or denied to them.

Users can be assigned to many user groups, and depending on your security manager and your security configuration a user may be allowed the permissions of all the groups to which he or she belongs, a particular group specified when the user signed on, or a default group specified as part of the user definition. For more details see Using all groups to which a user belongs.

Note: For Micro Focus Directory Server access, users always have the permissions of all the groups to which they belong.
Parent topic: Managing an LDAP from the Enterprise Server UI
Related information
To add a user
To edit a user
To delete a user
To add a group
To edit a group
To delete a group
To add a resource class
To edit a resource class
To delete a resource class
To add a resource entity
To edit a resource entity
To delete a resource entity
To assign resource permissions
To view permissions for a user
To view permissions for a group
To assign resource permissions when using MFDS Internal Security


Managing User Access

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The property screens for a security manager definition can be used for adding, editing and deleting user, group and resource definitions held in the associated external security manager (ESM), and for specifying resource permissions. This functionality is dependent on the ESM module, with which you connect to the ESM, providing support, and on the ESM honouring the requests submitted through these screens. Where such support is not available, users, groups and resources must be managed through the tools provided with your external security manager. Please check the documentation provided with your ESM module for details.

In addition to the conditions listed above, the security manager definition must be included in the security manager list that is used by MF Directory Server.

  • To Add a User
  • To Edit a User
  • To Delete a User
  • To View Permissions for a User
Parent topic: Managing an LDAP from the Enterprise Server UI


To Add a User

In order to use these property screens, your user account must have User Administration permissions.

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers, and for the security manager to which the user is to be added, click the radio button in the Select column.
  3. Click Edit.
  4. Click Properties.
  5. Click Users.
  6. Click Add.
  7. Specify the user's details.

    For information about the entry fields, refer to the page help for this screen.

  8. Click Next.
  9. Type a description of the user in Description.
  10. For each user group of which the user is to be a member, select the group from User groups, and click <--Add.
  11. If you change your mind and want to remove the user from any group, select the group from Member of and click Remove-->.
  12. Click Add.
Enter the tasks the user should do after finishing this task (optional).
Parent topic: Managing User Access


To Edit a User

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the user definition that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Users.

    The users screen is divided into tabs. The label of the tab indicates the start character(s) of the user ids that are listed on the tab.

  7. Select the tab containing the user you wish to edit.
  8. Click Edit for the user.
  9. Specify the user's details.

    For information about the entry fields, please refer to the page help for this screen.

  10. Click OK.
Parent topic: Managing User Access


To Delete a User

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the user to be deleted by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Users.

    The users screen is divided into tabs. The label of the tab indicates the start character(s) of the user ids that are listed on the tab.

  7. Select the tab containing the user you wish to delete.
  8. Click Edit for the user that you wish to delete.
  9. Click Delete.
  10. Click OK on the User Delete Confirmation page.
Parent topic: Managing User Access


To View Permissions for a User

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the user definition that you want to view by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Users.

    The users screen is divided into tabs. The label of the tab indicates the start character(s) of the user ids that are listed on the tab.

  7. Select the tab containing the user you wish to edit.
  8. Click Edit for the user.
  9. Click Permissions.

    The screen displays a tree structure. Expanding the top level node displays the various resource classes. Expanding a class displays the resource entities that it contains and the permissions that the user has for those entities. Please note, the permissions displayed are for those Access Control List entries that apply to the user, either by fully specifying the user's ID or by a wildcard match.

Parent topic: Managing User Access


Managing Groups

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The property screens for a security manager definition can be used for adding, editing and deleting user, group and resource definitions held in the associated external security manager (ESM), and for specifying resource permissions. This functionality is dependent on the ESM module, with which you connect to the ESM, providing support, and on the ESM honouring the requests submitted through these screens. Where such support is not available, users, groups and resources must be managed through the tools provided with your external security manager. Check the documentation provided with your ESM module for details.

In addition to the conditions listed above, the security manager definition must be included in the security manager list that is used by MF Directory Server

  • To Add a Group
  • To Edit a Group
  • To Delete a Group
  • To View Permissions for a Group
Parent topic: Managing an LDAP from the Enterprise Server UI


To Add a Group

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager to which the group will be added by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties.
  6. Click Groups.
  7. Click Add.
  8. Specify the details for the group.

    The group name cannot exceed eight characters and longer names will be truncated to the first eight characters. For more information about the entry fields, please refer to the page help for the screen.

  9. Click Next.
  10. Under Permissions, check each permission that you want to grant to the group. If you want to grant all permissions under the Directory Server Administration or Servers sections, click the appropriate Allow All button.

    The permissions are displayed in an inverted tree structure. Those on lower branches include the permissions on the branches from which they descend. For example, the permission to restore a repository includes the permission to import a repository. Therefore, restore is shown as a descendant of import.

    When you grant a particular permission, any permissions that it includes are automatically granted. Hence, when you check the Restore Repository permission, the Import Repository permission is automatically checked as well.

    Where a check box for a permission is greyed out, it indicates that the permission is included by other permissions that have been granted to the group. To revoke a permission that is included by others, you must first revoke those other permissions.

  11. Type a description of the user in Description.
  12. For each user group of which the user is to be a member, select the group from User groups, and click <--Add.
  13. If you change your mind and want to remove the user from any group, select the group from Member of and click Remove-->.
  14. Click Add.
Parent topic: Managing Groups


To Edit a Group

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to perform this, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the group that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Groups.
  7. Click the Edit button adjacent to the group you want to edit.
  8. Specify the details for the group.

    For information about the entry fields, please refer to the page help for the screen.

  9. Click OK.
Parent topic: Managing Groups


To Delete a Group

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to perform this, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the group that you want to delete by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Groups.
  7. Click the Edit button adjacent to the group you want to delete.
  8. Click Delete.
  9. Click OK on the Delete User Group confirmation page.
Parent topic: Managing Groups


To View Permissions for a Group

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

Note:

Please note that the display and setting of permissions for MFDS Internal Security differs from that for other Security Managers, and is covered separately by To assign resource permissions when using MFDS Internal Security.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the group definition that you want to view by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Groups.
  7. Click Edit for the group.
  8. Click Permissions.

    The screen displays a tree structure. Expanding the top level node displays the various resource classes. Expanding a class displays the resource entities that it contains and the permissions that the group has for those entities. Please note, the permissions displayed are for those Access Control List entries that apply to the group, either by fully specifying the group ID or by a wildcard match.

Parent topic: Managing Groups


Assigning Resource Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The property screens for a security manager definition can be used for adding, editing and deleting user, group and resource definitions held in the associated external security manager (ESM), and for specifying resource permissions. This functionality is dependent on the ESM module, with which you connect to the ESM, providing support, and on the ESM honouring the requests submitted through these screens. Where such support is not available, users, groups and resources must be managed through the tools provided with your external security manager. Please check the documentation provided with your ESM module for details.

In addition to the conditions listed above, the security manager definition must be included in the security manager list that is used by MF Directory Server.

In order to use these property screens, your user account must have User Administration permissions. .

  • About Resource Security
  • To Add a Resource Class
  • To Add a Resource Entity
  • To Assign Resource Permissions
  • To Edit a Resource Class
  • To Edit a Resource Entity
  • To Assign Resource Permissions When Using MFDS Internal Security
  • To Delete a Resource Class
  • To Delete a Resource Entity
Parent topic: Managing an LDAP from the Enterprise Server UI


About Resource Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can control access by a transaction to the following types of resource:

  • Files
  • Transient data queues
  • Temporary storage queues
  • Journals
  • Other transactions
  • To Enable Resource Security
Parent topic: Assigning Resource Permissions


To Enable Resource Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To enable resource security, do the following:

  1. Specify that a transaction is to perform resource security checking, by checking Security: Resource Level Checking on the PCT page in ESMAC for the transaction. (By default, transactions do not perform resource security checking.)
  2. Specify a set of resource keys in the resource table entry (for example, the FCT entry for a file). Each resource key is a number in the range 1 through 24.
  3. Specify a set of resource keys in a user's SNT entry. A user can access a resource if one or more of the resource keys for the resource matches a resource key specified in that user's SNT entry.

The figure below illustrates the process of resource key checking.

Figure 1. Resource key checking
Resource key checking
Parent topic: About Resource Security


To Add a Resource Class

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource class definition that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Resources.
  7. Click Add.
  8. Specify the details for the resource class.

    For information about the entry fields, please refer to the page help for the screen.

  9. Click Add.
Parent topic: Assigning Resource Permissions


To Add a Resource Entity

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager to which the resource will be added by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class to which the new resource will belong.
  8. Click Add.
  9. Specify the details for the resource.

    For information about the entry fields, please refer to the page help for the screen.

  10. Click Add.
Parent topic: Assigning Resource Permissions


To Assign Resource Permissions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties.
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class to which the resource belongs.

    This displays a list of available resources.

  8. Click the Edit button adjacent to the resource.
  9. Specify the Access Control List(ACL) string for the resource.

    The ACL specifies the access rights for the resource entity. Each entry in an ACL is referred to as an Access Control Entry, or ACE. These entries are separated by semi-colons.

    Each ACE specifies an actor, which is a user, a wildcard pattern for users, or a group, and one or more permissions that are granted (allow) or denied (deny) to that actor. The format for the ACE is as follows:

    setting:actor:action-1,...,action-n

    Where:

    • setting is allow or deny
    • actor is the name of a user, a pattern with one or more wildcards (see Wildcards) string that will be matched against the user's name, or a group name or wildcard pattern followed by a space and the word group (eg "ADMIN group")
    • action-1 through action-n are permission tokens:
      • none
      • execute
      • read
      • update
      • add
      • delete
      • control
      • alter
      • all

    For example, the following ACL string:

    allow:Test group:Execute,Read,Update,Add,Delete;allow:Operator group:Read

    assigns the Test group execute, read, update, add and delete permissions for the resource, and assigns the Operator group read permission.

  10. Click OK.
Parent topic: Assigning Resource Permissions


To Edit a Resource Class

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource class definition that you want to edit by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class you want to update.
  8. Specify the details for the class.

    For information about the entry fields, please refer to the page help for the screen.

  9. Click Apply.
Parent topic: Assigning Resource Permissions


To Edit a Resource Entity

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class to which the resource belongs.

    This displays a list of available resources.

  8. Click the Edit button adjacent to the resource.
  9. Specify the details for the resource.

    For information about the entry fields, please refer to the page help for the screen.

  10. Click OK.
Parent topic: Assigning Resource Permissions


To Assign Resource Permissions When Using MFDS Internal Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The display and setting of permissions when using MFDS Internal Security differs from that of other security managers. In its model, you cannot create resource entities, or define Access Control Lists for them. Instead there is a predefined set of permissions, which you view and set through the permissions tab when editing user groups. Users inherit their permissions from the groups to which they belong.

The instructions below are for setting permissions for a group. For instructions on adding users to groups, see To assign one or more users to a user group and To assign a user to one or more user groups.

Note:

The permissions that you grant to a group for starting, stopping, adding, deleting and modifying enterprise servers can also be overridden for individual enterprise servers. For details, see To assign permissions on a specific enterprise server when using MFDS Internal Security.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the MFDS Internal Security Manager by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Groups.
  7. Click the Edit button adjacent to the group you want to assign permissions to.
  8. Under Permissions, check each permission that you want to grant to the group. If you want to grant all permissions under the Directory Server Administration or Servers sections, click the appropriate Allow All button.

    The permissions are displayed in an inverted tree structure. Those on lower branches include the permissions on the branches from which they descend. For example, the permission to restore a repository includes the permission to import a repository. Therefore, restore is shown as a descendant of import.

    When you grant a particular permission, any permissions that it includes are automatically granted. Hence, when you check the Restore Repository permission, the Import Repository permission is automatically checked as well.

    Where a check box for a permission is greyed out, it indicates that the permission is included by other permissions that have been granted to the group. To revoke a permission that is included by others, you must first revoke those other permissions.

Parent topic: Assigning Resource Permissions


To Delete a Resource Class

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource class definition that you want to delete by clicking the relevant radio button in the Select column.
  4. Click Edit .
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class you want to delete.
  8. Click Delete.
  9. Click OK on the Delete Confirmation page.
Restriction: You cannot delete a class which contains resources.
Parent topic: Assigning Resource Permissions


To Delete a Resource Entity

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In order to use these property screens, your user account must have User Administration permissions.

  1. Click Security under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  2. Click Security Managers.
  3. Select the security manager containing the resource by clicking the relevant radio button in the Select column.
  4. Click Edit.
  5. Click Properties .
  6. Click Resources.

    This displays a list of available resource classes.

  7. Click the Edit button adjacent to the resource class to which the resource belongs.

    This displays a list of available resources.

  8. Click the Edit button adjacent to the resource.
  9. Click the Delete.
  10. Click OK on the Delete Confirmation page.
Parent topic: Assigning Resource Permissions


Migrating from Enterprise Server Early Versions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For Enterprise Server releases after release 5.0 Websync 2, the Enterprise Server security architecture changed significantly. The topics in this section cover issues relating to migrating your security configurations from earlier releases.

  • Integrating Security from Early Releases: casesm
  • Exporting MFDS Internal Security Definitions
Parent topic: Securing an Enterprise Server Installation


Integrating Security from Early Releases: casesm

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The CAS ESM Module (casesm) uses the Enterprise Server legacy security definitions (stored in the CICS resource tables).

Parent topic: Migrating from Enterprise Server Early Versions


Exporting MFDS Internal Security Definitions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The topics in this section describe the process you use to export the configurations defined in the MFDS Internal Security module so that you can use them to configure an Active Directory.

  • To Export Micro Focus LDAP Schema Extensions
  • To Export Users and Groups to an LDIF File
  • To store the directory server repository in an LDAP server
Parent topic: Migrating from Enterprise Server Early Versions


To Export Micro Focus LDAP Schema Extensions

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Before you can use an LDAP repository to hold information for Micro Focus applications, its schema must be extended to support the Micro Focus objects. To do this, you create an LDIF (Lightweight Directory Interchange Format) file containing the extensions.

Use themfds -L command line options to do this.

Syntax:

mfds -L [schema partition Distinguished Name] option ldif-filename [schema-version-1] [schema-version-2]

Parameters:

schema partition Distinguished Name | Specifies the DN of the partition in the Directory Information Tree where the schema definition is held. The schema partition holds, amongst other things, attributeSchema and classSchema objectclass instances.
option | Specifies the target directory server type: 0 = Microsoft Active Directory Lightweight Directory Server (AD LDS), 1 = Active Directory (Default), 2 = OpenLDAP, 3 = Sun Directory. Note: If you specify the ldif-filename, you must also specify a value for this parameter.
ldif-filename | Specifies the name of the destination file. Default: mfds_schema_[ mfds version ].ldf (e.g. mfds_schema_1.05.09.ldf)
schema-version-1 | Specifies the version of the schema extensions to be generated: 0 = current schema version (Default). Numbers greater than 0 specify older schema versions.
schema-version-2 | This option is used for upgrading from a previous schema. If schema-version-2 is specified and is less the schema-version-1, the output file is a delta between the schema-version-1 and schema-version-2. If schema-version-2 is greater than or equal to schema-version-1, this option is ignored.

Example:

To create a LDIF file called mfds-schema.ldf specifically for an Active Directory using the this_machine.mycom.com AD server, issue:

mfds -L DC=mycom,DC=com 1 c:\mfds-schema.ldf

However, in practice, rather than using a specific schema partition DN value, administrators may want to have a portable LDIF file where the root DN can be specified externally. If the Windows LDFIDE tool is used to extend the repository schema, the generated LDF file could use DC=X as the schema partition name. This can then be replaced at import time. For example,

mfds -L DC=X 1

should be sufficient for most installations.

Parent topic: Exporting MFDS Internal Security Definitions


To Export Users and Groups to an LDIF File

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. To export existing Directory Server users and groups from the MF Directory Server repository to an LDIF file, use the mfds -e command. The syntax is as follows:

    mfds -e root DNuser partition DNgroup partition DNresource partition DNschema formatldif-filenamesec-path

    root DN | The application partition to which all of the exported entries will be assigned.
    user partition DN | The name of the container within the application partition to which the exprted users will be assigned.
    group partition DN | The container within the application partition to which the exported groups will be assigned.
    resource partition DN | The container within the application partition to which the exported resource definitions will be assigned.
    schema format | Values: 1 = Active Directory (Default), 2 = OpenLDAP.
    sec-path | The location of the MF Directory Server repository.

    For example, the following command exports MF Directory Server users, groups and resources to an Active Directory compatible LDIF file.

    mfds -e "CN=Micro Focus,CN=Program Data,DC=local" "CN=Enterprise Server Users"
"CN=Enterprise Server Groups" "CN=Enterprise Server Resources" 1 mfdsusers.ldf
    CN=Micro Focus,CN=Program Data,DC=local | specifies the application partition to which all exported entries will be assigned
    CN=Enterprise Server Users | specifies the container within the application partition to which the exported users will be assigned
    CN=Enterprise Server Groups | specifies the container within the application partition to which the exported groups will be assigned
    CN=Enterprise Server Resources | specifies the container within the application partition to which the exported resource definitions will be assigned
Parent topic: Exporting MFDS Internal Security Definitions


To store the directory server repository in an LDAP server

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Update the schema of the target LDAP server to support the Enterprise Server configuration objects. How you do this will vary slightly depending on the particular LDAP server that you are using. In all cases, you will use the MFDS -L command to create an LDIF file containing the necessary extensions and then use the relevant import command for your LDAP server.
  2. Click Options under Configure on the menu on the left-hand side of an Enterprise Server Administration Web page.
  3. From the drop-down list under Repository location select ldap://.
  4. Specify the LDAP server, connection information and the LDAP credentials required to write to the server.
Parent topic: Exporting MFDS Internal Security Definitions


Security Reference Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section contains security-related reference information.

  • Environment Variables used in Enterprise Server Security
  • Resource Classes used by Enterprise Server
  • Solutions, Restrictions, and Changes in Behavior
Parent topic: Securing an Enterprise Server Installation


Environment Variables used in Enterprise Server Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following topics are concerned with the environment variables that you are likely to use in the context of Enterprise Server security.

  • Enterprise Server Default Users and Associated Environment Variables
Parent topic: Security Reference Information


Enterprise Server Default Users and Associated Environment Variables

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Enterprise Server has a set of default users that are used when no user is logged on for ESMAC authentication:
Environment | User | Associated Environment Variable
ESMAC | mfuser | ES_USR_DFLT_ESMAC

Using the environment variables, the default users can be overwritten by the users of your choice. For instance we could overwrite the ESMAC default user using in the region configuration.

configuration:
[ES-Environment]
ES_USR_DFLT_ESMAC=ESMACUSR
Parent topic: Environment Variables used in Enterprise Server Security


Resource Classes used by Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Each item (e.g. program, file, transaction) to which access is controlled is a called a resource. A resource has a name and a class, which indicates the type of the resource. For example, each enterprise server is a resource, and all enterprise servers belong to the same resource class.

A resource name must be unique within its class. That is, you can define two or more resources with the same name, provided that they belong to different classes.

Resources, such as ES configuration definitions in MFDirectory Server, use resource class names defined by Micro Focus. Users can also define their own resource classes for performing explicit access checks in applications.

When a user requests access to a resource the security facility relays the request to the external security manager, specifying the user, the resource and the resource class. The security manager will then look for resource rules that match the resource name. The processing of a request is dependent on the external security manager.

The entities and classes used are specified in the tables listed below.

  • Resource Classes for ESMAC and Operator Command Security
  • Resource Classes for MF Directory Server
    Describes the resource classes and entities that are used to control access to the functionality of Enterprise Server Administration.
Parent topic: Security Reference Information


Resource Classes for ESMAC and Operator Command Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.
The list below defines the name of each default resource class used in Enterprise Server for ESMAC and operator command security, its meaning, the type of resource entities it contains, and the minimum permission that a user requires on the entities.
OPERCMDS
Relation
Class for operator commands used by casstart/casstop/casfile/cassub/casout... commands
Entities
ES Commands
Access Level
Alter
MFESMAC
Relation
MAC Class for controlling access to ESMAC Resources
Entities
Entity | Description
TABLE | If your user has "Update" access to this resource then they will have the ability to interact with the majority of ESMAC function. Primary items controlled by this setting are the appearance of the buttons for controlling the SEPS (Tracing, Stopping), Stopping the Server, Accessing the console.log, trace data, dump data. If a user has "None" then they will not be shown any buttons other than the Server Status Button and the Monitoring button in addition to the Chg User button which allows them to sign-on. The basic effect of no access to this resource is that they are treated in the same way as an unauthenticated user. If they have "Read" access they will be shown the options but will be unable to perform any updates. If they have "Update" access or greater than they have full control of these functions.
GRP | This resource controls access to the buttons under the Resources drop down when the By Group selection is utilized. If the user has "Update" access to this resource then they will be able to access all the buttons that appear under the Resources pulldown when the By Group selection is made.
URI, XAT, XLT | This controls the access a user has to the various resources when selected via the By Type or Active menus under the Resources pulldown. "None" indicates that they can do nothing with this resource type, "Read" indicates that they can see the current settings, and "Update" indicates that they can modify the entries of this type.
Access Level
None, Read, Update
Parent topic: Resource Classes used by Enterprise Server


Resource Classes for MF Directory Server

Describes the resource classes and entities that are used to control access to the functionality of Enterprise Server Administration.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: The management of permissions for MFDS Internal Security differs from that for other Security Managers, and is covered separately by Legacy Directory Server Security Model.
  • Class - Enterprise Server Administration
  • Class - Servers
Parent topic: Resource Classes used by Enterprise Server


Class - Enterprise Server Administration

Restriction: This topic applies only when the Enterprise Server feature is enabled.
This class contains a set of predefined entities that correspond to the screens and functions used to manage the configuration of MF Directory Server and to access the user, group and resource property screens for security managers. The entities, the functions that they control, and the permissions that a user requires are as follows:
Entity | Controls | Permission required
Repository Access | Saving a copy of the repository to a file system directory. | Read
 | Importing data from a file system directory. | Add
 | Restoring a repository from a file system directory. The process of restoring overwrites all of the information in the current repository. | Add, Delete
 | Deletion of the entire Directory Server repository including all enterprise servers. | Add, Delete
Options | Changing of Directory Server options. | Update
Object Permissions | Allocation of permissions on individual enterprise servers. | Update
Directory Discovery | Viewing of a list of the Directory Servers that your Directory Server can detect on the network. | Execute
Execution Control | Shutting down of the Directory Server. | Execute
User Administration | Management of user accounts and user groups, and the setting of permissions. | Update, Add, Delete
Parent topic: Resource Classes for MF Directory Server


Class - Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The entities contained in this class correspond to, and control the configuration of, Enterprise Servers.

Entity | Controls | Permission required
Server Name | Viewing of enterprise server configuration information. | Read
 | Starting and stopping of enterprise servers. | Execute
 | Modification of configuration information for an enterprise server. | Update
 | Adding of listeners, services and packages to an enterprise server. When set as a default permission for the group, it also permits the adding of enterprise servers. | Add
 | Deletion of enterprise servers, and of listeners, services and packages from an enterprise server. | Delete
Parent topic: Resource Classes for MF Directory Server


Solutions, Restrictions, and Changes in Behavior

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Service Deployment and Security
  • Configuring Credentials for Starting and Stopping Enterprise Servers
  • Sign-on Disabled for Default Users
  • Configuring Sun Java System Directory as a Security Manager
Parent topic: Security Reference Information


Service Deployment and Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Enterprise Server provides a deployment feature to let developers package COBOL programs as Web Services or EJBs and deploy them to an Enterprise Server instance. The deployment process uploads the packaged service (in the form of a COBOL Archive or "CAR" file) to ES, then invokes an installer (mfdepinst) that extracts the contents from the archive, creates package and service objects in the Micro Focus Directory Server repository, and notifies ES of the new service.

Service deployment is initiated by a deployment client, running under the control of a developer or administrator. Deployment clients include those generated by the Interface Mapping Toolkit (IMTK), or the imtkmake command-line tool. All of these are documented elsewhere

Deployment and Security

Creating service and package objects in the MFDS repository requires update access, which may not be granted to all users. mfdepinst has to present credentials (a username and a password) to MFDS when it tries to create those objects. In a secured installation, deployment requests from users may fail to create service and package objects because of insufficient permissions.

The default configuration installed with Enterprise Server lets mfdepinst create objects in the MFDS repository, but when security options are changed it's easy to cause deployment requests to fail. (This is actually the appropriate behavior; when an installation is secured, it should prevent unauthorized access.) This is particularly true when external security is enabled.

How Deployment Credentials are Verified and Authorized

In early releases of Enterprise Server, the credentials sent to MFDS by mfdepinst were verified against entries in the file cciusers.dat. In more recent releases, MFDS keeps its own database of user information as part of the repository.

External security, which is enabled by specifying an external security manager (ESM) for MFDS security, lets MFDS use an outside facility, such as an LDAP server, to verify user credentials.

How MFDS is configured determines how the username and password sent by mfdepinst will be verified, and what determines their level of access. If you are using internal security, you'll have to ensure that the username and password sent by mfdepinst are configured in MFDS, and that the user account used by mfdepinst has "add" access for the MFDS repository. Similarly, if you're using external security, your ESM will have to accept the username and password sent by mfdepinst and grant it access to add objects to MFDS.

The ES Administration Guide discusses these topics in more detail.

How Deployment Credentials are Set

With Net Express version 5.0, WebSync 2 or later you can specify a username and password when deploying a service interface to a secure server either through the Net Express IDE or when using imtkmake from the command line.

Parent topic: Solutions, Restrictions, and Changes in Behavior


Configuring Credentials for Starting and Stopping Enterprise Servers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you start or stop an enterprise server from MF Directory Server, you are given the option of supplying two sets of credentials. The first is the operating system credentials under which the processes are to run (this is labelled Start/Stop processes as). The second, labelled Use Enterprise Server credentials of: is checked by the security features of MF Directory Server and Enterprise Server. The requirements of this second set of credentials are described below.

When an enterprise server starts, it connects to MF Directory Server to obtain its configuration details and to update its status information. To do this, it requires suitable Directory Server user credentials (that is, credentials that Directory Server will verify and authorize through the External Security Facility). You can specify that it should connect using a built-in default user or using the credentials with which you are currently logged on to Enterprise Server Administration. Alternatively, you can specify a different Directory Server username and password.

If you choose to use the built-in default user, the process is as follows:

  1. The enterprise server is started by the casstart command.
  2. It connects to MF Directory Server to obtain its configuration settings via the default user, mf_mdsa.
  3. The enterprise server subsequently spawns its communications server(s), referred to as MFCS.
  4. MFCS connects to MF Directory Server using the default user, mf_cs. This user requires permissions to do things like reading and writing data to the MF Directory Server repository. For example, it can read what configuration the server has, and write changes to the status field.
  5. The enterprise server will then use another default user, mfuser, as the identity for operations.
  • mf_cs and mf_mdsa must exist in the security context of MF Directory Server. That is, depending on the security configuration, they must exist in one of the security repositories used by MF Directory Server. The users must also have suitable permissions. At this point in time, the users must be members of a group called "#System" and this group must have modify permission on the resource entity in the Servers class that corresponds to the enterprise server. For more on the resource classes and entities controlling access to MF Directory Server resources, see Resource Classes for MF Directory Server.
  • mfuser must exist within the security context of the enterprise server and must have appropriate permissions on the casstart entity in the OPERCMDS class. For more about OPERCMDS, see Resource Classes for ESMAC and Operator Command Security.

If you choose to use the credentials with which you are currently logged on to Enterprise Server Administration, or if you specify alternative credentials, the enterprise server and MFCS will use those credentials when connecting to MF Directory Server. The enterprise server will also use the credentials internally.

Therefore, the user that you specify must exist within the security domain of both the MF Directory Server and the enterprise server. In addition:

  • To read and update information in MF Directory Server

    In the MF Directory Server domain, it must be a member of the #System group, and this group must have modify permission on the resource entity in the Servers class that corresponds to the enterprise server

  • To run the start command in Enterprise Server

    In the context of the enterprise server, it must have alter permission on the casstart entity within the OPERCMDS resource class

To stop an enterprise server, the requirements are the same, except that the user requires alter permission on the casstop entity with the OPERCMDS resource class.

Note:

Where an external security manager is configured for the enterprise server, a userid and password must be supplied when stopping it through any external method, such as casstop.

Parent topic: Solutions, Restrictions, and Changes in Behavior


Sign-on Disabled for Default Users

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When security is enabled, the default users can no longer sign-on to the system from a terminal.

Parent topic: Solutions, Restrictions, and Changes in Behavior


Configuring Sun Java System Directory as a Security Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes the steps you need to perform in order to configure Sun Java System Directory to use it as an Enterprise Server security manager and configuration repository. Micro Focus has developed and tested under Sun Java System Directory Server Enterprise Edition 6.1. Later revisions of Sun Java System Directory should be compatible with Micro Focus Enterprise Server Security Manager and Configuration Repository but this is not guaranteed. Micro Focus will review any issues found in later releases of Sun Java System Directory but cannot guarantee compatibility.

Note:

The commands in this section make the following assumptions:

  • You have downloaded and installed Sun Java System Directory Server Enterprise Edition 6.1 as described on the Sun web site.
  • You have installed into /usr/local/dsee.
  • You are using port 3880. This is an arbitrarily-chosen port. Check with your system administrator to find out what ports are available on your system.
  • You are using the dsadm command-line tool instead of the Sun Java Web Console GUI Directory Service Control Centre.
  • You are using the scratch directory /usr/local/dsee/var/example.

You will need to change the commands if your installation uses settings other than these.

When configuring an external Security Manager connection on Solaris, it is possible to specify the use of the Sun-provided LDAP client module for LDAP communications with the external Security Manager. The following configuration text is required in the Security Manager Configuration Information area:

[LDAP]
provider=/usr/lib/libldap.so
Note: A Security Manager connection configured on Solaris is not limited to using Sun Java Directory Server. It can communicate with other LDAP-based external Security Managers such as Microsoft Active Directory or Open LDAP.
  1. To set up the Sun Directory Server configuration and database directories:
    1. Enter the following command:
      dsadm create -p 3880 /usr/local/dsee/var/example

      The following information is displayed: Choose the Directory Manager password:

    2. Specify the Directory Manager password.

      The following information is displayed: Confirm the Directory Manager Password

    3. Confirm the password.

      The following information is displayed: Use 'dsadm start '/usr/local/dsee/var/example'' to start the instance.

  2. To start the instance and confirm that it is running:
    1. Enter the following command:
      dsadm start /usr/local/dsee/var/example

      The following information is displayed: Server started: pid=24879

    2. Enter the following command:
      dsadm info /usr/local/dsee/var/example
      The following information is displayed:
      Instance Path | /usr/local/dsee/var/example
      Owner | hub(staff)
      Non-secure port | 3880
      Secure port | 1636
      Bit format | 64-bit
      State | Running
      Server PID | 24879
      DSCC url -
      SMF application name -
      Instance version | D-A00
    3. Use an LDAP browser to connect to the instance at machine-address:3880 using id DN: "cn=Directory Manager" and password "password" to confirm it is running. Currently only the RootDSE data is displayed.
  3. To extend the schema, create a text file called 99container.ldif in /usr/local/dsee/var/example/config/schema. The file should contain the following:
    dn:cn=schema
objectClasses:(1.2.840.113556.1.3.23 NAME 'container' SUP top STRUCTURAL MUST (cn))
  4. To generate the Micro Focus Schema Extension file, enter the following command:
    mfds -l DC=X 3	/usr/local/dsee/var/example/config/schema/99microfocus.ldif
  5. To ensure the Directory Server instance picks up the new schema files, enter the following command:
    dsadm restart /usr/local/dsee/var/example
  6. To confirm the Micro Focus schema has been installed, enter the following command:
    /usr/local/dsee/dsrk6/bin/ldapsearch -b cn=schema -v -h 127.0.0.1 -p 3880 -D "cn=Directory Manager" -w password "objectclass=*" > schema.txt

    This command dumps the active schema to a file called schema.txt . You can search this file to confirm that it includes the expected "container" and "microfocus" attributeTypes and objectClasses.

  7. To create a default suffix for an example DIT:
    1. Enter the following command:
      dsconf create-suffix -p 3880 dc=example,dc=com

      The following information is displayed: Enter "cn=Directory Manager" password:

    2. Specify the password.
  8. To confirm that the new suffix exists:
    1. Enter the following command:
      dsconf list-suffixes -p 3880

      The following information is displayed: Enter "cn=Directory Manager" password:

    2. Specify the password.

      The following information is displayed: dc=example,dc=com

  9. To import the standard shipped example LDIF file.
    1. Enter the following command:
      dsconf import -p 3880 /usr/local/dsee/ds6/ldif/Example.ldif dc=example,dc=com

      The following information is displayed: Enter "cn=Directory Manager" password:

    2. Specify the password.

      The following information is displayed:

      New data will override existing data of the suffix "dc=example,dc=com".

      Initialization will have to be performed on replicated suffixes.

      Do you want to continue [y/n] ?

    3. Press 'Y'

      The following information is displayed:

      ## Index buffering enabled with bucket size 40
      ## Beginning import job...
      ## Processing file "/usr/local/dsee/ds6/ldif/Example.ldif"
      ## Finished scanning file "/usr/local/dsee/ds6/ldif/Example.ldif" (160 entries)
      ## Workers finished; cleaning up...
      ## Workers cleaned up.
      ## Cleaning up producer thread...
      ## Indexing complete.
      ## Starting numsubordinates attribute generation. This may take a while, please wait for further activity reports.
      ## Numsubordinates attribute generation complete. Flushing caches...
      ## Closing files...
      ## Import complete. Processed 160 entries in 4 seconds. (40.00 entries/sec)
      Task completed (slapd exit code: 0).
  10. Refresh the LDAP browser to ensure that you can see the new DIT contents. There should be a new "example" DC, containing organizational units for groups and people.
  11. Add the standard Micro Focus containers:create a file /home/hub/staff/example/mf-containers-sun.ldif containing the following:
    dn: cn=Micro Focus,dc=example,dc=com
cn: Micro Focus
objectClass: container

dn: cn=Micro Focus,dc=example,dc=com
cn: Micro Focus
objectClass: container

dn: cn=Enterprise Server Users,cn=Micro Focus,dc=example,dc=com
cn: Enterprise Server Users
objectClass: container

dn: cn=Enterprise Server User Groups,cn=Micro Focus,dc=example,dc=com
cn: Enterprise Server User Groups
objectClass: container

dn: cn=MFDS Repository,cn=Micro Focus,dc=example,dc=com
cn: MFDS Repository
objectClass: container
  12. Add containers to the DIT:
    1. Enter the following command:
      /usr/local/dsee/dsrk6/bin/ldapmodify -a -v -h 127.0.0.1 -p 3880 -D "cn=Directory Manager" -w password -f /home/hub/staff/example/mf-containers-sun.ldif

      The following information is displayed:

      bin_ldapmodify: started Wed Sep 19 16:31:26 2007
      ldap_init( 127.0.0.1, 3880 )
      add cn:
      Micro Focus
      add objectClass:
      container
      adding new entry cn=Micro Focus,dc=example,dc=com
      modify complete
      add cn:
      Enterprise Server Resources
      add objectClass:
      container
      adding new entry cn=Enterprise Server Resources,cn=Micro Focus,dc=example,dc=com
      modify complete
      add cn:
      Enterprise Server Users
      add objectClass:
      container
      adding new entry cn=Enterprise Server Users,cn=Micro Focus,dc=example,dc=com
      modify complete
      add cn:
      Enterprise Server User Groups
      add objectClass:
      container
      adding new entry cn=Enterprise Server User Groups,cn=Micro Focus,dc=example,dc=com
      modify complete
      add cn:
      MFDS Repository
      add objectClass:
      container
      adding new entry cn=MFDS Repository,cn=Micro Focus,dc=example,dc=com
      modify complete
  13. Refresh the LDAP browser to ensure that you can see the new DIT contents. There should be a new "Micro Focus " container with the user "Enterprise Server" subcontainers.
  14. Add the Directory Server resources and users.
    1. Enter the following command:
      mfds -e "cn=Micro Focus,dc=example,dc=com" "cn=Enterprise Server Users" "cn=Enterprise Server User Groups" "cn=Enterprise Server Resources" 2 "/home/hub/staff/example/mfds-users-sun.ldif"
      Note:

      There is no difference between the OpenLDAP and Sun syntax for the generated LDIF file, so no Directory Server changes have been required.

  15. Import the generated mfds_users_sun.ldif file.
    1. Enter the following command:
      /usr/local/dsee/dsrk6/bin/ldapmodify -a -v -h 127.0.0.1 -p 3880 -D "cn=Directory Manager" -w password -f /home/hub/staff/example/mf-users-sun.ldif
  16. Refresh the LDAP browser to ensure that you can see the new DIT contents. The "Enterprise Server" subcontainers now contain the "Enterprise Server Administration", "schemaadmin" and "#"-prefixed Directory Server default user groups.
  17. In Directory Server, configure a new external security manager as follows:
    Name | Sun Directory 6.1 machine-address:3880
    Module | mldap_esm
    Connection Path | machine-address:3880
    Authorized ID | cn=Directory Manager
    Description | Test Sun Directory ESM
    Configuration Information | [LDAP]
    Base=cn=Micro Focus,DC=example,dc=com
    user container=CN=Enterprise Server Users
    group container=CN=Enterprise Server User Groups
    resource container=CN=Enterprise Server Resources
  18. Change the MF Server Directory Security Manager List to use this external security manager and turn on administrative security.
Parent topic: Solutions, Restrictions, and Changes in Behavior


Glossary

Restriction: This topic applies only when the Enterprise Server feature is enabled.

  • ACE
  • ACL
  • ADAM
  • ADSI Edit
  • Auditing
  • CLASS
  • ESF
  • ESM
  • LDAP
  • LDIF
  • Resource
  • schema
  • security manager
  • SNMP
Parent topic: Securing an Enterprise Server Installation


ACE

Access Control Entry: an entry in an Access Control List (ACL). It specifies an actor (e.g. a user or group) and the kinds of access that the actor has to a particular resource.
Parent topic: Glossary


ACL

Access Control List: a rule specifying what actors (typically users and groups) are allowed what kinds of access (e.g. read, update) to a resource (file, transaction, configuration object, etc). (Some ESMs may not implement ACLs as such, but they provide an equivalent scheme.)
Parent topic: Glossary


ADAM

Active Directory Application Mode (ADAM) is a part of Microsoft’s fully integrated directory services available with Windows Server 2003, and is built specifically to address directory-enabled application scenarios.
Parent topic: Glossary


ADSI Edit

Lightweight Directory Access Protocol (LDAP) editor that you can use to manage objects and attributes in Active Directory.
Parent topic: Glossary


Auditing

Auditing refers to collecting information on security-related events and preserving it in for later review.
Parent topic: Glossary


CLASS

In Micro Focus security terms, a CLASS is used to identify a collection of ENTITIES.
Parent topic: Glossary


ESF

The Micro Focus External Security Facility, which relays security queries to external security managers. This facility can run within both Enterprise Server and MF Directory Server.
Parent topic: Glossary


ESM

External Security Manager, another name for Security manager: any system outside MF Server that can respond to security queries. It might be the OS itself, or an LDAP server, or some other facility.
Parent topic: Glossary


LDAP

Lightweight Directory Access Protocol: a standard for configuration-data directories, particularly user directories. Microsoft Active Directory is an LDAP implementation.
Parent topic: Glossary


LDIF

LDAP Directory Interchange Format: a standard for transporting LDAP data and schema definitions between LDAP servers.
Parent topic: Glossary


Resource

Any item to which access is controlled. A resource has a name and a class. A resource name is unique within its class.
Parent topic: Glossary


schema

In LDAP, the organization of information in the directory. The schema defines the types of configuration objects, their attributes, and their relationships.
Parent topic: Glossary


security manager

The module and associated configuration information that the External Security Facility connects to.
Parent topic: Glossary


SNMP

Simple Network Monitoring Protocol: a standard protocol for communicating system status and administration information. SNMP clients (usually called "agents") send information about changes in system status ("alerts") to an SNMP server ("monitor" or "manager"). They also respond to the monitor's queries for current status, and may be written to accept some administrative commands from the manager as well. The current version of SNMP is SNMPv3, which includes security provisions.
Parent topic: Glossary


Using the Security Audit Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager logs the records of auditable events that take place during Enterprise Server operation. You can use these records for things such as checking for security breaches or unauthorized access, or for monitoring usage.

  • About the Audit Manager
  • Audit Manager Architecture
  • Getting Started with Auditing
  • Starting and Stopping the Audit Process
  • Configuring the AUDITFILE Emitter
  • Configuring the SNMP Emitter
  • Accessing Audit Data
  • Dumping Audit Files
  • Audit Manager Errors
  • Configuring a User Exit
  • Audit Manager APIs
Parent topic: Enterprise Server Security


About the Audit Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager can collect audit events generated by MFDS and by the SEPs running in an Enterprise Server installation. It can either write the information to a set of secure files, or output the information as SNMP events.

  • In a Windows environment, the default installation configures and starts the Micro Focus Audit Manager service.
    • If it's not already running, you can start this service from the Windows Services dialog box, or with the command:
      net start mfauditmgr
    • For flexibility, you can also run the Audit Manager directly, by running the mfauditmgr program located in $COBDIR/bin.
  • In a UNIX environment, you can run the Audit Manager service as a daemon.

You can configure Audit Manager behaviour using a configuration file. You specify this configuration file with the -c <filename> option.

You can log auditable events to file, or as SNMP events. With SMMP, you can use SNMP management software to analyze the events.

The Audit Manager provides a utility, and APIs, that you can use to generate reports from the audit files that the system generates. The Audit Manager also provides APIs with which you can perform operations such as customizing logging destinations, and configuring your applications to generate audit events.

Parent topic: Using the Security Audit Manager
Related concepts
Audit Setup Configuration File
Related reference
To Start the Audit Manager
To stop the Audit Manager


Audit Manager Architecture

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Audit event information is generated by SEPs, and by Micro Focus Directory Server (MFDS).

  • On a SEP, an Audit Manager process collects the audit events.
  • A Micro Focus Directory Server (MFDS) generates audit events and forwards these to the the system's Inter-Process Communications (IPC).

The IPC sends the audit events to the Audit Manager.

The Audit Manager's event consolidator process combines these events, and the Audit event emitter or emitters output them, either to a secure file, or as SNMP events.

This process is illustrated by the figure below:

  • About Audit Emitters
  • Audit Setup Configuration File
  • Default Audit Configuration
Parent topic: Using the Security Audit Manager


About Audit Emitters

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager uses audit emitters to output the audit data.

There are two emitters that you can configure:

  • The AUDITFILE emitter writes audit data to a file. You use the Audit Facility Administration utility to access this data.

    The AUDITFILE emitter writes records to a collection of secure audit files. You configure the number and the size of the audit files in the collection when you set up the emitter definition.

    To access the audit details, you use a command to produce reports from the audit files. Once you have accessed the data, you can dump the file, and it becomes available for re-use by the audit process.

  • The SNMP emitter generates audit data as SNMP events.

    You can use an SNMP management tool to access this data.

Note: If there are no emitters configured, audit events are discarded.
Parent topic: Audit Manager Architecture


Audit Setup Configuration File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can use a configuration file to configure audit setup. You specifiy the configuration file with the the auditmgr command's -c option when you start auditing. In the Windows environment, you can use the Micro Focus Audit Manager service Start Parameter to specify the configuration file.

An example configuration file is below:
mfaudit.dest=AUDITFILE
# Sets the output type to secure file.
mfaudit.emitter.auditfile#collectionsize=3
# Sets that the audit process uses three files only.
mfaudit.emitter.auditfile#location=C:\MFAudit\logs
# Sets the location where the files are to be created.
mfaudit.emitter.auditfile#file= audit.aud_$(GEN)
# Sets the auditing file names. The $(GEN) parameter
# sets that the filenames are numbered sequentially.
mfaudit.emitter.auditfile#maxfilesize=200
# Sets that audit files are closed when they reach
# a size of 200 KB
Parent topic: Audit Manager Architecture
Related concepts
About the Audit Manager
Related reference
To Start the Audit Manager
To stop the Audit Manager


Default Audit Configuration

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you start auditing without using a configuration file, the following defaults are used:

  • Shared memory is used as the IPC mechanism.
  • The Secure file emitter only is enabled, with the following characteristics:
    • Audit file collection size of 5.
    • 20 Mb maximum size of each audit file in the collection.
  • Location in which the audit files are created: The value set in the environment variable: MFAUDIT_LOGS
  • In the Windows environment, if the MFAUDIT_LOGS environment variable is not set, the audit logs are created in the location set by the following registry key:

    \HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Micro Focus\NetExpress\<version>\MFAUDIT\<version>\Install

Parent topic: Audit Manager Architecture


Getting Started with Auditing

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The sections in this topic provide an example of how to configure secure file auditing in a Windows environment. You can use a similar process to configure auditing in a UNIX environment.

Note: In the Windows environment, auditing runs as a Windows service. You can also run auditing from a command line, as a separate process. To do this, you use the mfauditmgr command.

1. Create a configuration file

In this section, you create the configuration file that the audit process is to use. The configuration file controls the audit process: sets up the location, number, and maximum size of the files that the Audit Manager creates.

The lines beginning with the # character are comments only.

  1. Create a folder to hold your configuration file and auditing logs, for example: C:\MFAudit
  2. In the directory you created, use a text editor to create the audit.cfg file, and add the following content. The lines starting with # are comments only:
    mfaudit.dest=AUDITFILE
# Sets the output type to secure file.
mfaudit.emitter.auditfile#collectionsize=3
# Sets that the audit process uses three files only.
mfaudit.emitter.auditfile#location=C:\MFAudit\logs
# Sets the location where the files are to be created.
mfaudit.emitter.auditfile#file= audit.aud_$(GEN)
# Sets the auditing file names. The $(GEN) parameter
# sets that the filenames are numbered sequentially.
mfaudit.emitter.auditfile#maxfilesize=200
# Sets that audit files are closed when they reach
# a size of 200 KB

2. Start the auditing service

In this section, you re-start the auditing service so that it uses the configuration file.

  1. In Windows Services, locate the Micro Focus Audit Manager service, and if it is started, stop it.
  2. Right-click the service, and select Properties.
  3. Select the General tab, and in the Start parameters field at the bottom of the dialog box, enter the following:
    -c C:\MFAudit\audit.cfg
  4. On the dialog box, click Start and check that the service starts without errors.
  5. In Windows Explorer, check that the log files have been created ready for use.

3. Configure an External Security Manager (ESM)

In this section, you configure the Operating System ESM so that it is available for use.

  1. Start an Enterprise Server Administration session, and in the left hand pane under Configure, select Security.

    The Security Options screen appears.

  2. Select the Security Managers tab, and click Add to display the Add Security Manager screen.
  3. In the Name field, enter a name, for example Windows ESM, and in the Module field, enter osesm to specify the security manager. Ensure that the Enabled checkbox is checked, and click Add to add the security manager.

4. Generate MFDS auditing events

In this section, you configure the Operating System External Security Manager (ESM) to generate auditing events for Micro Focus Directory Server.

  1. In the left hand pane, select Security.
  2. Select the MF Directory Server tab and at the bottom of the screen, and click the Change button.
  3. Select the radio button next to the Windows ESM item you created, and click Add. You are prompted for a login with MF directory server administration permissions.
  4. Enter a valid Enterprise Server Administration user ID, for example the default SYSAD, password SYSAD, and click OK. You are prompted for a user ID and password with Administer Users permissions. Enter your system login and click OK.
  5. Under the MF Directory Server tab, in the Security Facility Configuration area, select the Create audit events checkbox, and at the bottom of the screen, click Apply.

MFDS operations that are performed are now logged to the audit files.

5. Generate Enterprise Server audit events

In this stage, you configure the Audit Manager to collect records of events generated by Enterprise Servers that are running.

  1. In the left hand pane, select Security.
  2. Select the Default ES Security tab and under Default ES Security Manager List, click Add.
  3. Select the radio button next to the Windows ESM entry, and click Add.

6. Perform secure operations

In this section, you generate audit events to be logged.

  1. Log off the directory server and log back on again.
  2. Perform some enterprise server processes, for example starting and stopping regions.
  3. Repeat the process to generate some audit events that you can check.

7. View the audit logs

In this section, you make the audit records accessible for viewing, and generate a report.

  1. In Windows Explorer, check the audit files and verify by the file size and datestamp that the first audit file has logged the audit data.

  2. Open a command prompt, and navigate to the C:\MFAudit\logs folder.
  3. Use the following command to make the first audit file available for dumping:
    mfauditadm -p -f audit.aud_1
  4. Use the following command to generate an audit report from the dumped file:
    mfauditadm -r -o audreport.txt -f audit.aud_1
    The above command creates a file named audreport.txt, that contains the audit information.
Parent topic: Using the Security Audit Manager


Starting and Stopping the Audit Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You control auditing by starting or stopping the Audit Manager.

To capture audit events generated by audit-enabled products, you must configure and start the Audit Manager. You can start the process from the command line.

  • In the Windows environment, by default the Audit Manager runs as a service. You can control auditing by starting or stopping the Micro Focus Audit Manager service.
  • Under Unix and Linux you can configure the Audit Manager consolidator to run as a background process.

The Audit Manager consolidator obtains its configuration information from a file specified with a command line option.

  • To Start the Audit Manager
  • To stop the Audit Manager
Parent topic: Using the Security Audit Manager


To Start the Audit Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

Use this command to start the Audit Manager.

mfauditmgr [-c cfg-file] [-n name]

Parameters:

cfg-file Specifies the name of the configuration file that is to be used for defining which emitters are to be enabled etc.

If no configuration file is specified, the audit event consolidator instance is configured as follows:

  • Shared memory is used as the IPC mechanism.
  • The Secure file emitter only is enabled, with the following characteristics:
    • Audit file collection size of 5.
    • 20 Mb maximum size of each audit file in the collection.
  • Location in which the audit files are created: The value set in the environment variable: MFAUDIT_LOGS
name Specifies the name of the audit event consolidator instance. This is the name that applications will use to communicate with this audit event consolidator instance.

If this option is not specified, the machine name is used.

Parent topic: Starting and Stopping the Audit Process
Related concepts
About the Audit Manager
Audit Setup Configuration File
Related reference
To stop the Audit Manager


To stop the Audit Manager

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

This command stops the Audit Manager.

mfauditmgr -x [-n name]

Parameters:

-x | Stop the audit event consolidator instance
name | Specifies the name of the audit event consolidator instance. This is the name that applications will use to communicate with this audit event consolidator instance. If this option is not specified, the machine name will be used.

Comments:

You will only be allowed to stop an audit event consolidator instance if you are the owner (that is, the user that started it), or are a Windows Administrator. In Windows environments, you can use this command to stop the instance even if the instance has been started as a service.

Parent topic: Starting and Stopping the Audit Process
Related concepts
About the Audit Manager
Audit Setup Configuration File
Related reference
To Start the Audit Manager


Configuring the AUDITFILE Emitter

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The AUDITFILE emitter writes audit records to a collection of files. These files hold the records in a binary format, and can be processed using the audit file APIs or the Audit Manager Administration Utility.

When the current file in the collection has reached its maximum size, the emitter writes to the next file in the collection. When all files in the collection have reached their maximum file, the emitter attempts to re-use the first file in the collection. This fails if the contents of the audit file have not yet been dumped.

When the last available file in the collection becomes half full, the emitter writes a warning event to the Windows event log, or to the Unix syslog. When the last available file in the collection becomes full, the emitter writes an error event to the Windows event log, or to the Unix syslog.

When no files are available, the emitter attempts to cache audit events in memory until a file becomes available. When there is no memory available, the emitter removes events from the cache to allow it to cache the most recent events. When an audit file becomes available, the emitter generates an audit event that details how many audit events were lost, and writes this as the first event in the file.

An audit file cannot be dumped until it has reached its maximum size, or has been set by an administrator as available for dumping. Marking an active files as available for dumping causes the file to be closed immediately, and the next file in the collection becomes the active file.

  • Setting AUDITFILE Emitter Properties
  • Setting the Audit Output Type
  • Specifying a User-defined Emitter
Parent topic: Using the Security Audit Manager
Related reference
Setting AUDITFILE Emitter Properties
AUDITFILE User Exit
To Make the Active Audit File Available for Dumping
To Dump an Audit File
To Generate a Report for an Audit File
To Generate a Report for All Audit Files in a Collection


Setting AUDITFILE Emitter Properties

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

In the Audit Manager Configuration file, you use the following line to specify the AUDITFILE emitter output properties.

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

Parameters:

emitter-name | The name of the audit 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. Emitter names and property names are case-insensitive. See the table below for details.
property-value | Description
AuditfileExit | The name of a DLL(Windows) or shared object (Unix/Linux) that is to be invoked by the AUDITFILE emitter to report on emitter status changes (see AUDITFILE User Exit). The name of the exit specified should reside in a directory on PATH (Windows) or LIBPATH / LD_LIBRARY_PATH / SHLIB_PATH on Unix/Linux.
CollectionSize The number of audit files that will be created in a collection.

Used in conjunction with MaxFileSize.

Default: 5. Maximum 10.
File The name of the audit file to be written.

The following pseudo-variables may be used for the construction of the audit file name:

  • $(AUDITID) - the name of the audit event consolidator that invoked this emitter.
  • $(GEN) - the generation of the file starting from 1.
Default: mfaudit.$(AUDITID).aud_$(GEN)

For example, the second file in the audit file collection created by this emitter when invoked by the audit event consolidator named nwb-cpjdell would be: mfaudit.nwb-cpjdell.aud_2

Note: If the $(GEN) pseudo-variable is not included in the file specification, this emitter appends it.
Location The directory where the audit files are to be written.

Default: the location specified by the MFAUDIT_LOGS environment variable or the current directory if MFAUDIT_LOGS is not set. The emitter will write an error event to the to the Unix syslog, if it is unable to create audit files in the specified directory.

Note: The Audit Manager attempts to create the output audit file location if it does not already exist. If the creation of the directory specified by the Location property fails, it will use the default location. If the creation of the directory specified by the MFAUDIT_LOGS environment variable fails, the current directory will be used.
.

If the MFAUDIT_LOGS environment variable is not set when running as a Windows Service, the Audit Manager will output the audit files to the directory specified by the \HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Micro Focus\NetExpress\<version>\MFAUDIT\<version>\Install registry key ).

MaxFileSize The directory where the audit files are to be written.

The maximum size of an audit file in KB that will be written before the file is closed, and the next audit file in the collection is opened.

A file in the collection is identified by the $(GEN) pseudo-variable (see File property above). The first audit file in a collection will result in the $(GEN) pseudo-variable being set to 1, the second in the sequence will result in it being set to 2, and so on until CollectionSize is exceeded. Once the CollectionSize number of files has been reached, the sequence number will revert back to 1.

Default: 0x00005000, indicating 20 MB max file size

Comments:

mfaudit.emitter.emitter-name#property is used to set a property with the a name and value for the given emitter. Any property name and value can be set, irrespective as to whether the emitter will actually make use of it. The CBL_AUDIT_EMITTER_PROPERTY_GET API can be used by an emitter to retrieve property values as strings or numeric values.

Multiple mfaudit.emitter.emitter-name#property entries can occur in the configuration file, but for duplicates, the last-most entry is used.

Property names are case insensitive.

When any of the following common case-insensitive property values are used, they are held in two forms: the string as given, and a corresponding numeric value. An emitter can then use the CBL_AUDIT_EMITTER_PROPERTY_GET API to retrieve the numeric value of the property directly without needing to perform its own string conversion.

String Value | Numeric Value
ON | 1
OFF | 0
YES | 1
Y | 1
NO | 0
N | 0
TRUE | 1
FALSE | 0
ENABLED | 1
DISABLED | 0
numeric-string | n

Examples:

Set the audit file name, the number of files in the audit file collection, and the maximum size of each audit file in the backup set for the AUDITFILE emitter.

...
mfaudit.emitter.auditfile#collectionsize=3
mfaudit.emitter.auditfile#location=e:\audit
mfaudit.emitter.auditfile#file= myaudit.aud_$(GEN)
mfaudit.emitter.auditfile#maxfilesize=200
...

Audit files myaudit.aud_1, myaudit.aud_2, and myaudit.aud_3 are created in the directory e:\audit. Each of these files has a maximum size of 200kb.

Parent topic: Configuring the AUDITFILE Emitter
Related reference
AUDITFILE User Exit
Related information
Configuring the AUDITFILE Emitter


Setting the Audit Output Type

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

In the the Audit Manager Configuration file, you use the mfaudit.dest parameter to specify audit event output types or emitter destinations to use: to file or as SNMP events, or both.

mfaudit.dest=audit-emitter-list

Parameters:

audit-emitter-list
A list of comma or space separated audit emitter names. Emitter names are case-insensitive. The supplied emitter names are:
  • AUDITFILE

    Trace events are written to an audit file in a binary format. The resulting file can be processed using the audit file APIs or the Audit Manager Administration Utility.

  • SNMP

    Trace events are generated as SNMP events.

The default is: mfaudit.dest=AUDITFILE

Comments:

mfaudit.dest is used to specify the audit event output types that are to be used by the audit event consolidator instance . You can configure multiple types.

Examples:

The following entry specifies that tracing events are to be output to an audit file.

...
mfaudit.dest=AUDITFILE
...

The following entry specifies that tracing events are to be output using both the audit file and SNMP emitters.

...
mfaudit.dest=AUDITFILE,SNMP
...
OR
...
mfaudit.dest=AUDITFILE
mfaudit.dest=SNMP
...
Parent topic: Configuring the AUDITFILE Emitter


Specifying a User-defined Emitter

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

In the the Audit Manager Configuration file, you use the following line to define an audit emitter that you have created. That is, it assigns an emitter name to your emitter program. Once you use this command, you can then use this emitter with the mfaudit.dest configuration.

mfaudit.emitter.emitter-name=program-name

Parameters:

emitter-name | The name of the emitter being defined. This name can be specified in mfaudit.dest entries elsewhere in the configuration file. Emitter names are case-insensitive.
program-name | The name of the program that implements the emitter interface and that will be invoked by the audit facility when outputting events to the destination named by emitter-name.

Default:

Not applicable.

Comments:

mfaudit.emitter is used to define a user-specific emitter. Where there are multiple mfaudit.emitter for the same emiter, the last-most is used.

Note: We recommend that custom emitters that you use should be written in C. They should not be written in COBOL due to potential recursion issues during CTF tracing.

Examples:

1) Define a user-specific emitter named MYAUDIT and make it a default audit emitter.

...
mfaudit.emitter.MYAUDIT=myauditemitter.dll
mfaudit.dest=MYAUDIT
...

2) Replace the well-known AUDITFILE emitter.

...
mfaudit.emitter.AUDITFILE=myauditfileemitter.so
...
Parent topic: Configuring the AUDITFILE Emitter


Configuring the SNMP Emitter

Restriction: This topic applies only when the Enterprise Server feature is enabled.

SNMP installations are split into two parts: an SNMP Agent runs on the systems being managed, whilst a central Management Console or other Management Tool runs elsewhere to monitor and maintain the systems that are running the Agents. There may be more than one Agent on a given system, provided that they are all configured to avoid using the same UDP and/or TCP ports, and that the Management Tool is told which ports to use to contact the Agents.

Various specifications of SNMP exist. v1 is not widely used today. v2, and specifically v2c, is most common. Whilst v3 can be thought of as being v2c using encrypted data flows.

There are many Agent systems. These may be software used on various operating systems, or firmware operating within hardware devices such as network routers. Micro Focus does not supply any Agent software.

The SNMP Emitter for the Micro Focus Audit Manager supports multiple logical interfaces which in turn interface with specific Agent services. The following SNMP Agent interfaces are provided for use with Net Express.

Agent interface module | Supplied with | Supported SNMP version | Description
mf_audit_win_snmp.dll | All installations of Net Express and Server | v2 and v2c | This module supports installations of Microsoft's WinSNMP embedded SNMP service, which works with SNMP v2 and v2c.
mf_audit_net_snmp.dll | All installations of Net Express and Server | v2, v2c and v3 (with no authentication or encryption of data) | This module supports installations of Net-SNMP v5.4 and upwards.
mf_audit_net_snmp.dll | The optional Security Pack for Net Express and Server | v2, v2c and v3 (with authentication and encryption of data) | This module supports installations of Net-SNMP v5.4 and upwards.

To use any of these modules, make the appropriate entries in the configuration file used by the Micro Focus Audit Consolidator Process. For details of the configuration file, see The Audit Consolidator Process Configuration File. For details on starting the consolidator process and specifying the location of the configuration file, see To start an audit event consolidator.

For each of these modules, a sample configuration file is shipped. The files are mf_audit_net_snmp.cfg and mf_audit_win_snmp.cfg. These contain elements specific to each of the variants of Windows SNMP support, but they are not complete mfauditmgr configuration files. The contents of the relevant sample file, or files, must first be merged with the existing Audit Manager configuration file, and then the Audit Manager system service must be re-started before the changes will take effect.

Many configuration options are common to both agent installations, but there are some entries that are specifically for use with Net-SNMP: the WinSNMP agent only supports SNMP v1 and SNMP v2 Trap generation, whilst the Net-SNMP agent also supports SNMP v3. However, the only configuration element that changes between WinSNMP and Net-SNMP when using SNMP v2 Traps is the agent name item.

It is perfectly acceptable to switch between Agents by using a single configuration file and alternating the agent used between mf_audit_win_snmp and mf_audit_net_snmp then re-starting the mfauditmgr service. Any extra SNMP v3 parameters that may have been supplied for Net-SNMP will simply be ignored by the WinSNMP emitter. A v2 Trap will always be issued when WinSNMP is in use, regardless of the SNMP version configured.

However, to use v3 authentication you must have the mf_audit_net_snmp module supplied with the Security Pack. If you configure the use of authentication when using the mf_audit_net_snmp module with the base Net Express or Server product, the emitter will log an error message.

Here's an example of a configuration file which will trace Audit events to both SNMP and the standard AUDITFILE emitter. This configuration uses WinSNMP to send the SNMP Trap messages.

mfaudit.emitter.snmp                = snmpaudit
mfaudit.dest                             = auditfile,snmp

mfaudit.emitter.auditfile#collectionsize = 5
mfaudit.emitter.auditfile#location       = c:\logs
mfaudit.emitter.auditfile#maxfilesize    = 1

mfaudit.emitter.snmp#agent      = mf_audit_win_snmp
# location of the Trap receiver, the Management Console that will view the audit events
mfaudit.emitter.snmp#agent.host  = <target host name or IP address>
# use port 162, the IANA default port for UDP and TCP traps
mfaudit.emitter.snmp#agent.port  = 162
# default is to exclude the events 0,2,3,4,5,6, the example below excludes
# events with a category >9
mfaudit.emitter.snmp#agent.exclude.events=>9

# Mode of transport, either UDP or TCP
# The default is UDP. Although an option for v2 installations
# TCP is normally only used for SNMP v3
# and is still only optional for v3
mfaudit.emitter.snmp#agent.transport = UDP

# the SNMP community of installations in which this system exists
# community default is "public"
mfaudit.emitter.snmp#agent.community = public

# snmp_version can be either "2" or "3". If v3, extra parameters
# are also required, see below.
# The default is "2"
mfaudit.emitter.snmp#agent.snmp_version = 2

The only change required to re-configure this audit manager installation to emit Audit events to SNMP using Net-SNMP instead of WinSNMP is shown below.

mfaudit.emitter.snmp#agent       = mf_audit_net_snmp

There are several extra parameters that are required in order to configure an SNMP v3 environment for the sending of encrypted audit messages. These are covered in Working with SNMP v3.

  • Using the SNMP Audit Emitter
  • Using the SNMP Emitter with a Net-SNMP Agent
  • Working with SNMP v3
Parent topic: Using the Security Audit Manager


Using the SNMP Audit Emitter

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To use the SNMP Emitter, you must:

  1. Configure the SNMP Agent to emit Trap messages to a monitoring Management Tool location. To do this:
    1. Configure the SNMP Emitter to tell the Agent the location of the Management Tools that should receive the emitter Audit Events.
    2. If you are using the Net SNMP Agent, install the Micro Focus MIB file (see below) into the Net SNMP MIB database.
  2. Configure the Management Tool that is to monitor the trap output.
    1. Import the Micro Focus MIB file (see below) into the Management Tool's MIB database so that it can recognise the message content that it is going to receive from the Agent.
    2. Tell the Management Tool to accept SNMP Trap events from the location (and the port number if the Agent is not using default ports) of the originating Agent.

The Micro Focus MIB file, mf_audit_snmp.mib, is located in the $COBDIR\bin directory by default.

Note: Some MIB import tools require specific file extensions such as .mib or .mb, or just .txt. Ensure that you rename this file to match the requirements of your software before attempting to install the Micro Focus MIB extension.
Note: With the Microsoft WinSNMP Agent, the WinSNMP emitter will work without any further configuration beyond that contained in the audit configuration file.
Parent topic: Configuring the SNMP Emitter


Using the SNMP Emitter with a Net-SNMP Agent

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Windows systems always have WinSNMP installed unless it has been specifically removed or disabled - although, without a little configuration it is quiescent. This is not the case with Net-SNMP, which you must install by hand.

The installation and configuration of Net-SNMP is beyond the scope of this document. Please refer to the Net-SNMP documentation for details. The main project, along with binary distributions, can be found at www.net-snmp.org (binaries are at www.net-snmp.org/download.html).

Once you have installed Net-SNMP, you must add the Micro Focus MIB definitions to the Net-SNMP MIB database before it will accept any actions from the audit emitter. You do this by running mf_audit_net_snmp_deploy.bat, which is supplied in the $COBDIR\bin directory by default.

The default installation drive for Net-SNMP is c:\usr. However, this location is used is at the discretion of the installer. Therefore, the mf_audit_net_snmp_deploy.bat file has an optional location parameter for specifying the location in which it will attempt to install the MIB. This parameter takes long and spacey names, provided that they are delimited with quote characters. If no parameter is found, the file will attempt to install the MIB into a Net-SNMP installation located in c:\usr.

When you have installed and configured the Agent software, you can configure the audit emitter (see below).

  • Configuring the emitter
  • Specifying the location of management tools
  • Configuring logging for problem diagnosis
Parent topic: Configuring the SNMP Emitter


Configuring the emitter

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The configuration of each emitter can be viewed as two separate sections: where do you want the Trap messages to be received, and how do you want to send them. This breaks down into a series of location and format options.

The location information is always the same collection of:
  • Local agent (WinSNMP or Net-SNMP)
  • Destination location
  • Destination port
  • Transmission method
  • Events to be audited
  • SNMP version to be used
  • SNMP community identity

The format options vary widely depending upon the version of SNMP to be used.

Parent topic: Using the SNMP Emitter with a Net-SNMP Agent


Specifying the location of management tools

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Specifying the location of management tools that will receive events

In the configuration file for the SNMP emitter, the agent.host and agent.port entries configure the snmp emitter to tell the Agent which of its configured management tools should receive the emitted Audit Events. For example:

mfaudit.emitter.snmp#agent.host = 127.0.0.1

WinSNMP cannot handle DNS (text) names and will only accept dotted decimal notation IP addresses like the one shown in the example above.

Net-SNMP can handle DNS or Dotted Decimal notation for the host location.

The Internet Assigned Names Authority (IANA) defines the standard ports to be used for SNMP traffic. Although it is entirely possible that specific installations may choose to use other ports, the following are the defined standard group of ports:

  • snmp 161/tcp SNMP
  • snmp 161/udp SNMP
  • snmptrap 162/tcp SNMPTRAP
  • snmptrap 162/udp SNMPTRAP

The SNMP Audit Emitter only uses the SNMPTRAP ports. If any installations require an override of the port definitions, follow the guidance below for configuring the SNMP agents on your installation, and modify the mfaudit.emitter.snmp#agent.port line in the configuration file. Failure to do both sets of configuration will lead to indeterminate results.

mfaudit.emitter.snmp#agent.port = 162

The transmission method is either UDP or TCP. UDP is widely used as it is fast and has few system overheads. UDP was also the only transmission method available in the early days of SNMP. TCP is slower but it can be used to transmit more than a single IP packet of information, and if audited events are being truncated the user should switch to using TCP. When changing a working system, remember that both the receiver and sender must share a similar configuration, so the changes must be made at both ends of the link.

To select UDP, set transport = UDP. For TCP, set transport = TCP. The default is to use UDP.

mfaudit.emitter.snmp#agent.transport = UDP

The SNMP Trap versions are set using the "snmp_version" configuration option. Acceptable values are either "2" or "3". The default snmpv value is "2".

If SNMP v3 is selected and you wish to use the authentication and privacy features, several extra parameters are also required and you must have the Net SNMP emitter module that is supplied with the Security Pack. See Working with SNMP v3 for more details.

mfaudit.emitter.snmp#agent.snmp_version= 2

The actual range of events that will be audited through this emitter can be masked using the agent.exclude.events option. For more details of this option, see the general Audit Manager documentation. The default behaviour is to exclude events below those at category 9.

mfaudit.emitter.snmp#agent.exclude.events=>9

All SNMP v2 and v3 installations operate within logical communities of installations. If no community name is specified all SNMP installations will use the default community name "public".

To specify the community of your local installations and, in particular, that of the receiver of the SNMP audit events, you will need to add a community option to your configuration file. This name must not be spacey in form.

mfaudit.emitter.snmp#agent.community = community_name

Parent topic: Using the SNMP Emitter with a Net-SNMP Agent


Configuring logging for problem diagnosis

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Because audit emitters cannot use the Micro Focus Consolidated Tracing Facility (CTF) to produce diagnostic information, the SNMP emitter supports an alternative logging mechanism. This enables you to send log information to a file and optionally to the screen.

To use the logging mechanism, you use the agent.log_emitter, agent.log_to_screen and agent.logfilename entries in the configuration file. The sample below, illustrates the use of these entries. The comment lines (those preceded with #) document the allowable values.

# Emitters cannot use Micro Focus CTF trace facilities, so
# a basic alternative logging method has been provided.
#
# Logging can go to file and screen, or just to file.
#
# mfaudit.emitter.snmp#agent.log_emitter options
#
# on                  - enable all logging options
# off                 - do not log anything
# errors              - log only errors
# flow                - log module process flow
# content             - log audit message (partial) content
# errors_flow         - log errors and logic flow
# errors_flow_content - log errors and logic flow and content
mfaudit.emitter.snmp#agent.log_emitter = errors

# mfaudit.emitter.snmp#agent.log_to_screen options
# on                   - log to console screen
# off                  - do not log to screen, log to file
mfaudit.emitter.snmp#agent.log_to_screen = on

# mfaudit.emitter.snmp#agent.logfilename options
# if screen logging is disabled log to file name given here
mfaudit.emitter.snmp#agent.logfilename = c:\snmpemitter.log
Parent topic: Using the SNMP Emitter with a Net-SNMP Agent


Working with SNMP v3

Restriction: This topic applies only when the Enterprise Server feature is enabled.

SNMP v3 adds two optional levels of security to SNMP v2c Traps: Authentication and Privacy (Content Encryption).

To enable generated Audit events be sent using SNMP v3 flows, we rely upon software produced by the OpenSource Net-SNMP project. The main project along with binary distributions can be found at www.net-snmp.org. (Binaries are at www.net-snmp.org/download.html). This release of Micro Focus SNMP Audit Emitter was created to use Net-SNMP v5.4. It does not require a 3rd party OpenSSL installation, nor does it require an OpenSSL compliant Net-SNMP installation.

Note:
  • In order to use SNMP v3 with privacy and authentication, you must have the mf_audit_net_snmp.dll that is provided with the optional Micro Focus Security Pack, not the version that is supplied with the base product.
  • Microsoft Windows SNMP services do not include native SNMP v3 support, so the WinSNMP option will not provide SNMP v3.
  • The SNMP V3 Specific Configuration Options
  • Configuring the Micro Focus Audit Emitter for SNMP V3
Parent topic: Configuring the SNMP Emitter


The SNMP V3 Specific Configuration Options

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The use of SNMP v3 with authentication and privacy introduces the need to configure several basic options before the SNMP v3 Traps can be generated and sent. If you are not using authentication and privacy, you can ignore these options. They are as follows:

  • Security Engine ID
  • Username
  • Hash method (MD5 or SHA1)
  • Authentication password
  • Cipher (DES or AES128)
  • Cipher password

There are two further options which will only be used in a limited number of installations:

  • Context EngineID
  • ContextName

Depending upon the transmission privilege settings all of the options may be used. In most installations, all of the options are going to be required to enable correct authentication and cryptographically protected transmissions that can be received correctly at the management console where the trap messages are monitored.

The SNMP Audit Emitter can only send SNMP v3 traps under a single user identity. In order for the traps to be deciphered correctly, this identity must also be configured with exactly the same content at the receiver of the trap messages.

Parent topic: Working with SNMP v3


Configuring the Micro Focus Audit Emitter for SNMP V3

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The first change to a standard V2 installation is to enable V3 operations.

mfaudit.emitter.snmp#agent.snmp_version = 3

Now we must select the level of security privilege that we require on our transmissions.

Whilst Authentication can be enabled or disabled at will, Privacy can only be enabled when Authentication is already enabled. So the three transmission privilege permutations are:

NoAuth No authentication or encryption of data

AuthPriv Authenticate and use private (encrypted) data

AuthNoPriv Authenticate user with no encryption of data

When configuring the SNMP Audit Emitter, this choice is held in the "privilege" setting. The following example enables both Authorisation and Privacy.

mfaudit.emitter.snmp#agent.privilege = AuthPriv

When either Privacy or Authentication and Privacy are disabled, the relevant sections of the configuration are ignored.

To provided Authorisation, a user identity is configured at the monitoring trap receiver and the issuing Emitter. Five options define a user, and a further option defines the Security EngineID that groups the user within a logical group of users.

We shall now take a look at the User options in detail.

The Username
The username is a single text string with a simple name. This name cannot contain spaces.
mfaudit.emitter.snmp#agent.security_username = fred_jones
The Hash Method
The Hash Method and Authentication Pass Phrase (the Shared Secret in cryptographic terms) are combined to form a cryptic value. This value which will be compared with the receiver's similarly configured pairing which has a matching Username and Security EngineID. A mismatch will cause the authentication attempt to be rejected.

Most installations support the MD5 hash method, and later installations may also support SHA1. If configuring a new V3 user, you should choose to use the latest hash method installed at the monitoring location that will receive the traps. The original MD5 method is the default hash method as it will currently be pre-configured in more installations than SHA1.

mfaudit.emitter.snmp#agent.hmac = MD5

The chosen hash method is applied to a configured pass phrase. The pass phrase must be at least 8 characters in length and may be spacey if the phrase is contained within a single pair of quote characters. Non-spacey passwords may omit the quote characters.

mfaudit.emitter.snmp#agent.auth_passphrase = "auth password"
The Encryption Cipher
The Privacy cipher can be either DES or AES128. Like the SHA1 hash above, AES is a recent addition to SNMP V3 and may not be in place in all installations. As a result, the default setup is to use the DES cipher. As with choosing a hash method, if you are configuring a new v3 user you should choose to use the latest cipher method that is installed at the monitoring location that will receive the traps. This should ideally be AES, however the default setting is DES as this will match the majority of installations in the field today.

The three options are DES, AES and AES128. The latter two are equivalent. It is anticipated that additions to the SNMP V3 standard will add AES192 and AES256 support in the future. When this happens AES will refer to AES128.

mfaudit.emitter.snmp#agent.cipher = DES

Exactly the same rules apply to Privacy (Cipher) pass phrases and Authentication pass phrases.

mfaudit.emitter.snmp#agent.cipher_passphrase = "crypt password"
The Security Engine ID
Several copies of a given username can exist within an SNMP installation, however only one copy can exist within the scope of any one Security Engine. So the group of five options shown above are always paired with a Security Engine ID. This is a numerical string represented in hex format. There are many long and varied methods for determining what value to use for a security engine ID and there is as yet no formal consensus. This document is not the place to examine the arguments, however in the setup you will need to choose a value to use as the Security Engine ID. This must match the receiver's Engine ID and Username's config grouping of options.

The following example would work as an initial test value, however it lacks meaning in a wider SNMP context and your network management team should assign a security Engine ID for the Audit Emitter monitoring, or advise the user of an existing Engine ID that should be used.

mfaudit.emitter.snmp#agent.security_engineID = 0x0102030405

Putting this group together we have a collection that describes the user, the user's Security Engine in which it will work, and the methods of both proving the user's identity and encrypting the audit event's data content. Taken together this is the complete configuration describing a single user.

mfaudit.emitter.snmp#agent.privilege = AuthPriv
mfaudit.emitter.snmp#agent.security_engineID = 0x0102030405
mfaudit.emitter.snmp#agent.security_username = fred_jones
mfaudit.emitter.snmp#agent.hmac = MD5
mfaudit.emitter.snmp#agent.auth_passphrase = "auth password"
mfaudit.emitter.snmp#agent.cipher = DES
mfaudit.emitter.snmp#agent.cipher_passphrase = "crypt password"
The ContextID and ContextName
The final configuration items not mentioned so far are the Security Context ID and ContextName. These are paired together in much the same fashion as the SecurityEngineID and UserName to form a restricted connection entity.

Contexts can be useful in installations where several applications will be receiving SNMP data and the users do not wish all the applications to receive all the incoming data.

By giving different applications the same SecurityEngineID and UserName configuration, but different ContextEngine and ContextName configurations, data destined for specific locations can be sent to those locations without the need to configure extra Users in the SecurityEngine domain in order to distinguish the destinations and sources.

Again, in a similar fashion to the SecurityEngineID and UserName configuration items, the ContextEngineID is expected to be a hex string, and the ContextName a character string which usually has human readable content.

mfaudit.emitter.snmp#agent.context_engineID = 0x0102030405
mfaudit.emitter.snmp#agent.context_name = primary_audit_monitor
Parent topic: Working with SNMP v3


Accessing Audit Data

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Audit data is either written to files, or output as SNMP events. You use the mfauditadm command to access the audit output data.

Before you can access data from the active file, you must make it available for dumping.

  • To Generate a Report for an Audit File
  • To Generate a Report for All Audit Files in a Collection
  • To Dump and Generate a Report for an Audit File
  • To Dump and Generate Reports for All Audit Files in a Collection
  • To Make the Active Audit File Available for Dumping
Parent topic: Using the Security Audit Manager


To Generate a Report for an Audit File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this. To dump or generate a report for the active audit file, you must first make it available for dumping.

mfauditadm -r -o report-file-name] -f audit-file-name

Parameters:

-r | Generate a report
-f audit-file-name | The audit file from which the report is to be generated.
-o report-file-name | Name of the report file to be created. If this option is not specified, the report file will be derived from the audit-file-name, where the extension will be replaced by .txt. For example, if the audit-file-name was specified as mfaudit.DOCTEST.aud_3, the report file created would be named mfaudit.DOCTEST.txt

Example:

mfauditadm -r -o auditdata.txt -f mfaudit.DOCTEST.aud_5
Note:

Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again, until it has been reused by the audit consolidator process.

Parent topic: Accessing Audit Data
Related information
Dumping Audit Files
Configuring the AUDITFILE Emitter


To Generate a Report for All Audit Files in a Collection

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Facility Administration command line utility to do this.

mfauditadm -r -c [-o report-file-name] -f audit-file-name

Parameters:

-f audit-file-name | An audit file in the collection for which reports are to be generated.
-c | Generate a report for each available file in the collection.
-r | Generate a report.
-o report-file-name | Name of the report file to be created. If this option is not specified, the report file will be derived from the audit-file-name, where the extension will be replaced by .txt. For example, if the audit-file-name was specified as mfaudit.DOCTEST.aud_3, the report file created would be named mfaudit.DOCTEST.txt

Example:

mfauditadm -r -c -o auditdata.txt -f mfaudit.DOCTEST.aud_5
Note:

To dump or generate a report for the active audit file, you must first make it available for dumping. Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again, until it has been reused by the audit consolidator process.

Parent topic: Accessing Audit Data
Related information
Dumping Audit Files
Configuring the AUDITFILE Emitter


To Dump and Generate a Report for an Audit File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -r [-date date] [-time time] -d [-o report-file-name] -f audit-file-name

Parameters:

-f audit-file-name | The audit file to be dumped and for which a report is to be generated.
-d | Mark the file as dumped.
-r | Generate a report.
-o report-file-name | Name of the report file to be created. If this option is not specified, the report file will be derived from the audit-file-name, where the extension will be replaced by .txt. For example, if the audit-file-name was specified as mfaudit.DOCTEST.aud_3, the report file created would be named mfaudit.DOCTEST.txt

Example:

mfauditadm -r -d -o auditdata.txt -f mfaudit.DOCTEST.aud_5
Note:

To dump or generate a report for the active audit file, you must first make it available for dumping. Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again, until it has been reused by the audit consolidator process.

Parent topic: Accessing Audit Data


To Dump and Generate Reports for All Audit Files in a Collection

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -r -c -d [-o report-file-name] -f audit-file-name

Parameters:

-f audit-file-name | An audit file in the collection to be dumped and for which a report is to be generated.
-c | Include each available file in the collection.
-r | Generate a report for each file available for dumping.
-d | Mark the files as dumped
-o report-file-name | Name of the report file to be created. If this option is not specified, the report file will be derived from the audit-file-name, where the extension will be replaced by .txt. For example, if the audit-file-name was specified as mfaudit.DOCTEST.aud_3, the report file created would be named mfaudit.DOCTEST.txt

Example:

mfauditadm -r -c -d -o auditdata.txt -f mfaudit.DOCTEST.aud_5
Note:

To dump or generate a report for the active audit file, you must first make it available for dumping. Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again, until it has been reused by the audit consolidator process.

Parent topic: Accessing Audit Data


To Make the Active Audit File Available for Dumping

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

In order to access the active file's audit data, you need to make it available for dumping. You use the Audit Manager Administration command line utility to do this. After you perform this, it is no longer the active file, and you can access the data it contains.
Note: You can specify the audit file by either giving its name or the name of the audit event consolidator that uses it. If neither are specified, the command uses the current active file.
mfauditadm -p [-n instance-name]
mfauditadm -p [-f audit-file-name]

Parameters:

-p | Make the active audit file available for dumping
-n instance-name | Specifies the name of the audit event consolidator instance. This is the name that applications will use to communicate with this audit event consolidator instance. This option cannot be used with the -f option. If neither this option nor the -f option is not specified, the machine name will be used.
-f audit-file-name | Specifiies the name of the audit file to be made available for dumping. This option cannot be used with the -n option. An error will be reported if the named file is not an active audit file.

Example:

mfauditadm -p -f mfaudit.DOCTEST.aud_5
Parent topic: Accessing Audit Data
Related information
Dumping Audit Files
Configuring the AUDITFILE Emitter


Dumping Audit Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Audit files created by the AUDITFILE Emitter cannot be reused until they have been dumped. Dumping involves the creation of backup files or reports using the audit file APIs. Once an audit file has been dumped it is marked as being available for reuse.

An audit file cannot be dumped until:

  • It has reached its maximum size.

    or

  • It is marked as available for dumping using the Audit Manager Administration Utility.
  • To Dump an Audit File
  • To Dump All Audit Files in a Collection
Parent topic: Using the Security Audit Manager
Related reference
To Make the Active Audit File Available for Dumping
To Dump an Audit File
To Generate a Report for an Audit File
To Generate a Report for All Audit Files in a Collection


To Dump an Audit File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -d -f audit-file-name

Parameters:

-f | The audit file to be dumped.
-d | Mark the file as dumped.

Example:

mfauditadm -d -f mfaudit.DOCTEST.aud_5
Note:

To dump or generate a report for the active audit file, you must first make it available for dumping. Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again, until it has been reused by the audit consolidator process.

Parent topic: Dumping Audit Files
Related information
Dumping Audit Files
Configuring the AUDITFILE Emitter


To Dump All Audit Files in a Collection

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

You use the Audit Manager Administration command line utility to do this.

mfauditadm -d -c -f audit-file-name

Parameters:

-f audit-file-name | An audit file in the collection to be dumped.
-c | Dump each available file in the collection containing audit-file-name.
-d | Mark the files as dumped.

Example:

mfauditadm -d -c -f mfaudit.DOCTEST.aud_5
Note:

To dump or generate a report for the active audit file, you must first make it available for dumping. Once an audit file has been dumped, you cannot generate a report for it, nor can you dump it again, until it has been reused by the audit consolidator process.

Parent topic: Dumping Audit Files


Audit Manager Errors

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager can generate the following error messages:

  • AUD0002E: Failed to start server
  • AUD0003E: Failed to connect to server
  • AUD0004E :Failed to initialise audit facility
  • AUD0005E: Failed to allocate memory
  • AUD0006E: File does not exist
  • AUD0007E: File is not available for dumping
  • AUD0008E: No file is available for dumping
  • AUD0009E: Invalid file format
  • AUD0010E: Invalid file name
  • AUD0011E: File not dumped
  • AUD0012E: Operation failed
  • AUD0013E: Failed to create output file
  • AUD0029E: Failed to initialise CTF
  • AUD0030E: You are not authorised to stop the server
  • AUD0031E: Failed to install service
  • AUD0032E: Failed to uninstall service
  • AUD0033E: File is not active
  • AUD0034E: You are not authorised to perform this operation
  • AUD0036E: Semaphore fault
Parent topic: Using the Security Audit Manager


AUD0002E: Failed to start server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit manager server has failed to start.

Resolution

Note the events leading up to the error condition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors


AUD0003E: Failed to connect to server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit process has failed to connect to the audit manager server.

Resolution

Note the events leading up to the error condition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors


AUD0004E :Failed to initialise audit facility

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit facility has failed to initialise.

Resolution

Note the events leading up to the error condition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors


AUD0005E: Failed to allocate memory

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that a memory allocation process has failed.

Resolution

Note the events leading up to the error condition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors


AUD0006E: File does not exist

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that

Indicates that you attempted a dump operation on a non-existent file.

Resolution

Check your syntax and try again.

Parent topic: Audit Manager Errors


AUD0007E: File is not available for dumping

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the file you attempted to dump has not been made available for dumping.

Resolution

Use the mfauditadm -p command to make the file available for dumping.

Parent topic: Audit Manager Errors


AUD0008E: No file is available for dumping

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that you attempted a dump operation and no files have been made available for dumping.

Resolution

Use the mfauditadm -p command to make the file you want available for dumping.

Parent topic: Audit Manager Errors


AUD0009E: Invalid file format

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit file that you are attempting to dump is not a valid audit file.

Resolution

Check that the audit file you specified is valid and has been made available for dumping.

Parent topic: Audit Manager Errors


AUD0010E: Invalid file name

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that the audit output file configuration attempts to allocate an incorrect filename for the output files.

Resolution

Check that the audit output filename (configured in the Audit Manager Configuration file) is valid. Don't forget that the process attempts to append a number to each sequential output filename.

Parent topic: Audit Manager Errors


AUD0011E: File not dumped

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Indicates that an audit file dump operation failed.

Resolution

Check that the audit file has been made available for dumping, and that the location set to hold the dump output is valid, and has sufficient access permissions and space available to hold the dumped output.

Parent topic: Audit Manager Errors


AUD0012E: Operation failed

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An audit operation failed.

Resolution

Note the sequence of events that lead up to the message, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors


AUD0013E: Failed to create output file

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The audit process failed in its attempts to create the file to hold the audit output.

Resolution

Check that the location set to hold audit output (configured in the Audit Manager Configuration file) is valid, and has sufficient access permissions and space available to hold the audit output.

Parent topic: Audit Manager Errors


AUD0029E: Failed to initialise CTF

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Facility uses parts of the Consolidated Tracing Facility (CTF) infrastructure to provide functionality. The Audit Facility failed to initialise Consolidated Tracing Facility in order to access the functionaity it needs.

Resolution

If the problem persists, note the sequence of events leading up to the error and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors


AUD0030E: You are not authorised to stop the server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Your login ID does not have sufficient security access permissions to perform the operation.

Resolution

Use a login with the required permissions set, or contact your system administrator.

Parent topic: Audit Manager Errors


AUD0031E: Failed to install service

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The mfauditmgr -i command failed to install the consolidator service.

Resolution

Try starting the service manually. If the problem persists, contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors


AUD0032E: Failed to uninstall service

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The mfauditmgr -u command failed to uninstall the consolidator service.

Resolution

Try uninstalling the service manually. If the problem persists, contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors


AUD0033E: File is not active

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The file from which you are attempting the dumping operation is not the active audit file.

Resolution

Use the following command to set the file as the active file:
mfauditadm -p -f <filename>
Parent topic: Audit Manager Errors


AUD0034E: You are not authorised to perform this operation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Your login ID does not have sufficient security access permissions to perform the operation.

Resolution

Use a login with the required permissions set, or contact your system administrator.

Parent topic: Audit Manager Errors


AUD0036E: Semaphore fault

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An internal communications process has failed.

Resolution

Note the events leading up to the error condtition, and contact Micro Focus Technical Support.

Parent topic: Audit Manager Errors


Configuring a User Exit

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can invoke the AUDITFILE emitter user exit to report on emitter status changes. It is enabled by specifying its name to the AUDITFILE emitter using the configuration file's mfaudit.emitter.emitter-name#property entry.

  • AUDITFILE User Exit
Parent topic: Using the Security Audit Manager


AUDITFILE User Exit

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The interface to the AUDITFILE_EMITTER_EXIT entry point is as follows:

  • AUDITFILE emitter initialising: The exit may change the emitter's properties during its invocation.
  • AUDITFILE emitter deinitialising: The exit would typically release any resources it has acquired during its previous invocations.
  • The name of the audit file being made active.
  • The name of the audit file that is now full.
  • No audit files are available for outputting events to.

The AUDITFILE emitter loads the DLL or shared object named by the AuditfileExit property and invokes the AUDITFILE_EMITTER_EXIT entry point within it whenever an emitter status change occurs.

Syntax:

typedef cobrtncode_t (*PFI_AUDITFILE_EMITTER_EXIT)(cobuns32_t function,
                                                   cobuns8_t *emitter_name,
                                                   ...);

On Entry:

function
AUDITFILE emitter status change:
0 | AUDITFILE emitter initialising. The exit may change the emitter's properties during its invocation
1 | AUDITFILE emitter deinitialising. The exit would typically release any resources it has acquired during its previous invocations
2 | A new audit file is being made active
3 | The active audit file is now full
4 | There are no audit files available for outputting events into
emitter name
The name of the emitter invoking the exit
...
A variable number of parameters depending on the value of function. When:
function=0 | no additional parameters
function=1 | no additional parameters
function=2 | 1 additional parameter: a null-terminated filename
function=3 | 1 additional parameter: a null-terminated filename
function=4 | no additional parameters

On Exit:

Nothing

Return Codes:

Dependent upon the exit function. At present this should always be 0.

Comments:

Please note that the user exit should not be written in COBOL.

See auditfile_exit.c for an example.

Parent topic: Configuring a User Exit
Related reference
Setting AUDITFILE Emitter Properties
Related information
Configuring the AUDITFILE Emitter


Audit Manager APIs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Audit Manager provides APIs that you can use to audit-enable your applications, create your own audit emitters and process audit files.

  • API Return Codes
  • Audit Events
  • Audit Configuration APIs
  • Audit Event Generation APIs
  • Audit Event Consolidator APIs
  • Audit File Processing APIs
  • Audit Emitter Interface
  • Structure and Typedefs
Parent topic: Using the Security Audit Manager


API Return Codes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

These return codes are provided in the mfaudit.cpy copybook for COBOL programs, and the mfaudit.h include file for C programs.

Value | Name | Description
0 | 78-AUD-RET-SUCCESS | Success
-1 | 78-AUD-RET-FAILURE | Unspecified Failure
1 | 78-AUD-RET-INVALID-HANDLE | Invalid audit or audit file handle specified
2 | 78-AUD-RET-INVALID-AUDIT-CATEGORY | Invalid audit category specified
5 | 78-AUD-RET-NOT-ENOUGH-MEMORY | Memory allocation error
6 | 78-AUD-RET-OUTPUT-ERROR | Error outputting to one or more output destinations
7 | 78-AUD-RET-PROPERTY-NOT-FOUND | Property not found
8 | 78-AUD-RET-BUFFER-TOO-SMALL | Buffer length too small
9 | 78-AUD-RET-VALUE-NOT-INTEGER | Value is not an integer
10 | 78-AUD-RET-EMITTER-NOT-FOUND | Emitter not found
12 | 78-AUD-RET-ZERO-LENGTH-DATA | Zero length data specified
13 | 78-AUD-RET-INVALID-PROP-NAME | Invalid property name specified
14 | 78-AUD-RET-INVALID-COMP-NAME | Invalid component name specified
15 | 78-AUD-RET-INVALID-EMITTER-NAME | Invalid emitter name specified
19 | 78-AUD-RET-NO-SERVER-PROCESS | mfauditmgr process is not running
20 | 78-AUD-RET-ACCESS-DENIED | Unable to access resource(s)
1000 | 78-AUD-RET-FILE-NOT-EXIST | File does not exist
1001 | 78-AUD-RET-FILE-NOT AVAILABLE | File(s) not available for dumping
1002 | 78-AUD-RET-FILE-INVALID-FORMAT | Unrecognised audit file format
1003 | 78-AUD-RET-FILE-EOF | End of file
1004 | 78-AUD-RET-FILE-NO-MORE-RECORDS | No more records left to process
1005 | 78-AUD-RET-FILE-INVALID-NAME | Invalid audit file name
1006 | 78-AUD-RET-FILE-NOT-DUMPED | Audit file has not been dumped
Parent topic: Audit Manager APIs


Audit Events

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Event Category | Component Identifier | Event Identifier | Event Data | Description
Audit Facility (1) MF.AUDITMGR 0
  1. mfauditmgr instance name (text)
  2. mfauditmgr instance type (4-byte comp-5)

    0 = command line

    1 = Windows service

 mfauditmgr starting
1
  1. mfauditmgr instance name (text)
 mfauditmgr stopping
2 | None | Request received from mfauditadm -p to deactivate the active file
Parent topic: Audit Manager APIs


Audit Configuration APIs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit Configuration APIs are available:

  • CBL_AUDIT_CONFIG_PROPERTY_GET
    Get an audit configuration property value.
  • CBL_AUDIT_CONFIG_PROPERTY_SET
    Sets an audit configuration property value.
Parent topic: Audit Manager APIs


CBL_AUDIT_CONFIG_PROPERTY_GET

Get an audit configuration property value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_CONFIG_PROPERTY_GET" using by value     flags
                                           by reference property-name
                                           by reference property-vallen
                                           by reference property-value
                                              returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
property-name | pic x(n) | pic x(n)
property-vallen | cblt-x4-comp5 | pic x(4) comp-5
property-value | pic x(n) | pic x(n)

On Entry:

Control flags

Bit | Value | Meaning
0 | 0 | Return string value. Use bit 1 to determine string terminator
 | 1 | Return integer value. Ignore bit 1.
1 | 0 | Return the value as a space-terminated string
 | 1 | Return the value as a null-terminated string
2-28 |  | Reserved for future use (must be 0)
29 | 0 | property-name is space-terminated
 | 1 | property-name is null-terminated
30-31 |  | Reserved for future use (must be 0)

property-name: Space- or null- terminated (depending upon setting of bit 29) case-insensitive property name.

NAME | mfauditmgr instance name to connect, or are connected, to
NOSERVER_ACTION | indicates the desired behaviour of the CBL_AUDIT_EVENT API when the mfauditmgr process is not running. A value of "wait" indicates the API will block (the default). A value of "nowait" indicates the API will return an error.
SYSTEM | name of the system to be associated with audit events output by this process

property vallen: Length of property-value buffer in which property value is to be returned. The routine fails if this is too small for the value to be returned. This parameter is ignored if value is being returned as an integer.

On Exit:

property-vallen | Length of returned string value in property-value buffer. Length does not include termination character. If property-value is null, or if the specified buffer length is too small for the value to be returned, property-vallen will be set to the required buffer length. This parameter is not set if the value is being returned as an integer.
property-value | Buffer in which the property value is to be returned. This is either a pic x(n) field for a value being returned as a string, or a pic x(4) comp-5 field for a value being returned as an integer. A null property-value may be specified to request that the API returns the required buffer length to hold the specified property value.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-PROPERTY-NOT-FOUND
78-AUD-RET-BUFFER-TOO-SMALL
78-AUD-RET-VALUE-NOT-INTEGER
78-AUD-RET-INVALID-PROP-NAME

Comments:

CBL_AUDIT_CONFIG_PROPERTY_GET is used to retrieve a named property value associated with the audit facility's configuration for the current process.

Supported properties are yet to be defined.

Examples:

Get the value associated with the audit facility's "system" property.

copy "mfaudit.cpy" .

01 flags           pic x(4) comp-5.
01 prop-len        pic x(4) comp-5.
01 prop-string     pic x(100).
...
compute flags = 78-AUD-FLAG-PROP-STRING-VALUE
move length of prop-string to prop-len

call "CBL_AUDIT_CONFIG_PROPERTY_GET" using
                                     by value flags
                                     by reference "system "
                                     by reference prop-len
                                     by reference prop-string
...
Parent topic: Audit Configuration APIs


CBL_AUDIT_CONFIG_PROPERTY_SET

Sets an audit configuration property value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_CONFIG_PROPERTY_SET" using by value     flags
                                           by reference property-name
                                           by reference property-value
                                              returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
property-name | pic x(n) | pic x(n)
property-value | pic x(n) | pic x(n)

On Entry:

flags
Bit | Value | Meaning
0 | 0 | String value. Use bit 1 to determine string terminator
1 | Integer value. Ignore bit 1.
1 | 0 | String value is space-terminated
1 | String value is null-terminated
2-28 | Reserved for future use (must be 0)
29 | 0 | property-name is space-terminated
1 | property-name is null-terminated
30-31 | Reserved for future use (must be 0)
property-name
Space- or null- terminated (depending upon setting of bit 29) case-insensitive property name. Recognised property names are:
NAME | mfauditmgr instance name to connect, or are connected, to
NOSERVER_ACTION | indicates the desired behaviour of the CBL_AUDIT_EVENT API when the mfauditmgr process is not running. A value of "wait" indicates the API will block (the default). A value of "nowait" indicates the API will return an error.
SYSTEM | name of the system to be associated with audit events output by this process
Note: Other property names may be set, but they will be ignored by the facility.

On Exit:

Nothing.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-INVALID-PROPERTY-NAME

Comments:

CBL_AUDIT_CONFIG_PROPERTY_SET is used to set a named property value for the audit facility's configuration for the current process. If a property with the same name already exists, its value will be replaced with the new value.

Supported properties are yet to be defined.

Examples:

Set the audit facility's "system" property value.

copy "mfaudit.cpy ".

01 flags           pic x(4) comp-5.
01 prop-string     pic x(100).
...
compute flags = 78-AUD-FLAG-PROP-STRING-VALUE
move "ESDEMO" & x"00" to prop-string

call "CBL_AUDIT_EMITTER_PROPERTY_SET" using
                                    by value flags
                                    by reference "system "
                                    by reference prop-string
...
Parent topic: Audit Configuration APIs


Audit Event Generation APIs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit Event Generation APIs are available:

  • CBL_AUDIT_EVENT
    Outputs an audit event.
  • CBL_AUDIT_HANDLE_GET
    Get an audit handle.
  • cobaudit_event
    Outputs an audit event.
Parent topic: Audit Manager APIs


CBL_AUDIT_EVENT

Outputs an audit event.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_EVENT" using by value     flags
                             by reference component-id
                             by reference audit-event
                                returning status-code

Table 1. Parameters
 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-id | pic x(n) | pic x(n)
audit-event | cblt-aud-event | Group containing
cblte-audevt-version | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-flags | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-id | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-category | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-data-count | cblt-x4-comp5 | pic x(4) comp-5
cblte-audevt-reserved1 | cblt-x4-comp5 | pic x(4) comp-5 occurs 7
cblte-audevt-event-len | cblt-pointer | pointer
cblte-audevt-event-type | cblt-pointer | pointer
cblte-audevt-event-data | cblt-pointer | pointer
cblte-audevt-reserved2 | cblt-pointer | pointer occurs 7

On entry

Control flags

Bit | Value | Meaning
0-12 | Reserved | for future use (must be 0)
13 | 0 | cblte-audevt-event-data is an array of pointers to trace data of varying size and type. The corresponding elements of the cblte-audevt-event-len and cblte-audevt-event-type arrays need to be set up.
 | 1 | cblte-audevt-event-data is an array of pointers to trace data of the same size and type. Only the first element of cblte-audevt-event-len and cblte-audevt-event-type need to be set up.
14-29 |  | Reserved for future use (must be 0)
30 | 0 | component-id is space-terminated
 | 1 | component-id is null-terminated
 |  | (ignored if bit 31 unset)
31 | 0 | component-id is an audit handle created by CBL_AUDIT_HANDLE_GET (pic x(4) comp-5).
 | 1 | component-id is a text string (pic x(n)) . The termination character for the string is defined by bit 30.
component-id
Component identifier. This will either be a pic x(4) comp-5 tracer handle (See CBL_AUDIT_HANDLE_GET() - Get an Audit Handle for details about how a component acquires an audit handle) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.
cblte-audevt-version
Structure version. Must be 0.
cblte-audevt-flags
Control flags. Must be 0.
cblte-audevt-id
Component specific audit event identifier used to identify the type of event being output
cblte-audevt-category
Category of the audit event being output.
Value Category
0 Unknown
1 Audit Facility
2 System
3 Security API request check
4 Security API request define
5 Security API request other
6 Security API result allow
7 Security API result deny
8 Security API result error
9 Security API result success
cblte-audevt-data-count
Number of audit data items. Indicates the number of elements in the cblte-audevt-event-len, cblte-audevt-event-type, and cblte-audevt-event-data arrays. May be 0.
cblte-audevt-event-len
Pointer to array of 4-byte comp-5 items. Each array element indicates the length of the corresponding audit data item in the cblte-audevt-event-data array. May be NULL if cblte-audevt-data-count is 0.
cblte-audevt-event-type
Pointer to array of 4-byte comp-5 items. Each array element indicates the type of the corresponding audit data item in the cblte-sudevt-event-data array. May be NULL if cblte-audevt-data-count is 0.
Value Type
0 Binary
1 Text (local encoding)
2 Address
3 COMP-5
4 COMP-X
5 UTF8
6 Signed COMP-5
7 Signed COMP-X
cblte-audevt-event-data
Pointer to array of pointer items. Each array element addresses an audit data item of the type and length indicated by the corresponding element in the cblte-audevt-event-type and cblte-audevt-event-len arrays respectively. May be NULL if cblte-audevt-data-count is 0.

N.B. for address type items, the array element is the address value, and not a pointer to the address value.

On Exit:

Nothing

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-INVALID-HANDLE
78-AUD-RET-INVALID-AUDIT-CATEGORY
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-OUTPUT-ERROR
78-AUD-RET-INVALID-COMPONENT-NAME
78-AUD-RET-NO-SERVER-PROCESS
78-AUD-RET-ACCESS-DENIED

Comments:

None

Examples:

copy "mfaudit.cpy".

78 78-EVENT-TYPE-A      value 1.
78 78-EVENT-TYPE-B      value 2.

01 audit-event          cblt-aud-event.
01 audit-event-lengths  pic x(4) comp-5 occurs 1.
01 audit-event-pointers pointer occurs 1.
01 audit-event-types    pic x(4) comp-5 occurs 1.
01 audit-handle         pic x(4) comp-5.
01 audit-info           pic x(10).
01 component-id         pic x(7) value "mycomp ".
01 flags                pic x(4) comp-5.

...
move low-values to audit-event

set cblte-audevt-event-len of audit-event to
    address of audit-event-lengths(1)
set cblte-audevt-event-type of audit-event to
    address of audit-event-types(1)
set cblte-audevt-event-data of audit-event
    to address of audit-event-pointers(1)

1) Acquire an audit handle to trace "mycomp" component audit events, and then output two audit events: one with event data, one without.

call "CBL_AUDIT_HANDLE_GET" using by value 0
                                  by reference component-id
                                  by reference audit-handle
...
move 0 to flags
move 78-AUD-FLAG-CATEGORY-UNKNOWN to
     cblte-audevt-category of audit-event
move 78-EVENT-TYPE-A to cblte-audevt-id of audit-event
move 1 to cblte-audevt-data-count of audit-event
move length of audit-info to audit-event-lengths(1)
move 78-AUDIT-EVENT-TYPE-TEXT to audit-event-types(1)
set audit-event-pointers(1) to address of audit-info

call "CBL_AUDIT_EVENT" using by value flags
                             by reference audit-handle
                             by reference audit-event
...
move 78-EVENT-TYPE-B to cblte-audevt-id of audit-event
move 0 to cblte-audevt-data-count of audit-event

call "CBL_AUDIT_EVENT" using by value flags
                             by reference audit-handle
                             by reference audit-event
...

2) Output two informational events for the "mycomp" component without acquiring an audit handle

...
move 78-AUD-FLAG-COMPID-STRING to flags
move 78-AUD-FLAG-CATEGORY-UNKNOWN to
     cblte-audevt-category of audit-event
move 78-EVENT-TYPE-A to cblte-audevt-id of audit-event
move 1 to cblte-audevt-data-count of audit-event
move length of audit-info to audit-event-lengths(1)
move 78-AUDIT-EVENT-TYPE-TEXT to audit-event-types(1)
set audit-event-pointers(1) to address of audit-info

call "CBL_AUDIT_EVENT" using by value flags
                             by reference component-id
                             by reference audit-event
...
move 78-EVENT-TYPE-B to cblte-audevt-id of audit-event
move 0 to cblte-audevt-data-count of audit-event

call "CBL_AUDIT_EVENT" using by value flags
                             by reference component-id
                             by reference audit-event
...
Parent topic: Audit Event Generation APIs


CBL_AUDIT_HANDLE_GET

Get an audit handle.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_HANDLE_GET" using by value     flags
                                  by reference component-name
                                  by reference audit-handle
                                     returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
component-name | pic x(n) | pic x(n)
audit-handle | cblt-x4-comp5 | pic x(4) comp-5

On Entry:

flags
Bit | Value | Meaning
0-29 | Reserved for future use (must be 0)
30 | 0 | component-name is space-terminated
1 | component-name is null-terminated
(ignored if bit 31 unset)
31 | Reserved for future use (must be 0)
component-name
Space- or null-terminated (depending upon bit 30 setting) case-insensitive component identifier string.

On Exit:

audit-handle
Audit handle to be specified to the CBL_AUDIT_EVENT API.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-INVALID-COMPONENT-NAME

Comments:

Components should invoke this API to acquire an audit handle before performing any auditing operations. This API returns an audit handle that should be passed to the CBL_AUDIT_EVENT API.

Please note that the CBL_AUDIT_EVENT API allows a component to be specified as a handle or as a string depending upon its flags parameter specification. This allows events to be output without first acquiring an audit handle by specifying a component identifier string instead. However, this will have an impact on performance as the component identifier will be validated each time.

Examples:

Acquire an audit handle to output "mycomp" audit events.

copy "mfaudit.cpy".

01 audit-handle    pic x(4) comp-5.
01 component-name  pic x(7) value "mycomp".
...
call "CBL_AUDIT_HANDLE_GET" using by value 0
                                  by reference component-name
                                  by reference audit-handle
...
Parent topic: Audit Event Generation APIs


cobaudit_event

Outputs an audit event.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

cobrtncode_t cobaudit_event(cobuns32_t      flags_p,
                   const cobuns8_t *component_id,
                   AUDIT_EVENT     *audit_event)

On Entry:

Control flags
Bit | Value | Meaning
0-29 |  | Reserved for future use (must be 0)
30 | 0 | component-name is space-terminated
 | 1 | component-name is null-terminated
 |  | (ignored if bit 31 unset)
31 |  | Reserved for future use (must be 0)
component_id
Component identifier. This will either be a 32-bit unsigned integer tracer handle (See CBL_AUDIT_HANDLE_GET() - Get an Audit Handle for details about how a component acquires an audit handle) if bit 31 of flags is not set, or a text identifier if bit 31 of flags is set.
audit_event
Audit event structure
version | Structure version. Must be 0.
flags | Control flags. Must be 0.
event_id | Component specific event identifier used to identify the type of event being output.
event_category | Audit event category.
data_count | Number of audit data items. Indicates the number of elements in the event_len, event_type, and event_data arrays. May be 0.
event_len | Pointer to array of 32-bit unsigned integers. Each array element indicates the length of the corresponding audit data item in the event_data array. May be NULL if data_count is 0.
event_type Pointer to array of 32-bit unsigned integers. Each array element indicates the type of the corresponding audit data item in the event_data array. May be NULL if data_count is 0.
Any value other than the ones specified above will be treated as type 0 (binary).
0 Binary
1 Text (local encoding)
2 Address
3 COMP-5
4 COMP-X
5 UTF8
6 Signed COMP-5
7 Signed COMP-X
event_data Pointer to array of pointer items. Each array element addresses an audit data item of the type and length indicated by the corresponding element in the event_type and event_len arrays respectively. May be NULL if data_count is 0.

N.B. for address type items, the array element is the address value, and not a pointer to the address value.

On Exit:

Nothing

Return Codes:

AUDIT_RET_SUCCESS
AUDIT_RET_INVALID_HANDLE
AUDIT_RET_INVALID_AUDIT_CATEGORY
AUDIT_RET_NOT_ENOUGH_MEMORY
AUDIT_RET_OUTPUT_ERROR
AUDIT_RET_INVALID_COMPONENT_NAME
AUDIT_RET_NO_SERVER_PROCESS
AUDIT_RET_ACCESS_DENIED

Comments:

cobaudit_event() is intended for use by C programs. It outputs the specified event identified by event_id to one or more output destinations.

Parent topic: Audit Event Generation APIs


Audit Event Consolidator APIs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit Event Consolidator APIs are available:

  • CBL_AUDIT_EMITTER_PROPERTY_GET
    Get an audit emitter property value.
  • CBL_AUDIT_EMITTER_PROPERTY_SET
    Set an audit emitter property value.
Parent topic: Audit Manager APIs


CBL_AUDIT_EMITTER_PROPERTY_GET

Get an audit emitter property value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_EMITTER_PROPERTY_GET" using by value     flags
                                            by reference emitter-name
                                            by reference property-name
                                            by reference property-vallen
                                            by reference property-value
                                               returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
emitter-name | pic x(n) | pic x(n)
property-name | pic x(n) | pic x(n)
property-vallen | cblt-x4-comp5 | pic x(4) comp-5
property-value | pic x(n) | pic x(n)

On Entry:

flags
Bit | Value | Meaning
0 | 0 | Return string value. Use bit 1 to determine string terminator
1 | Return integer value. Ignore bit 1.
1 | 0 | Return the value as a space-terminated string
1 | Return the value as a null-terminated string
2-27 | Reserved for future use (must be 0)
28 | 0 | emitter-name is space-terminated
1 | emitter-name is null-terminated
29 | 0 | property-name is space-terminated
1 | property-name is null-terminated
30-31 | Reserved for future use (must be 0)
emitter-name
Space- or null-terminated (depending upon setting of bit 28) case-insensitive emitter name.
property-name
Space- or null- terminated (depending upon setting of bit 29) case-insensitive property name.
property-vallen
Length of property-value buffer in which property value is to be returned. The routine fails if this is too small for the value to be returned.

Ignored if value is being returned as an integer.

On Exit:

property-vallen | Length of returned string value in property-value buffer. Length does not include termination character. If property-value is null, or if the specified buffer length is too small for the value to be returned, property-vallen will be set to the required buffer length. Not set if the value is being returned as an integer.
property-value | Buffer in which the property value is to be returned. This is either a pic x(n) field for a value being returned as a string, or a pic x(4) comp-5 field for a value being returned as an integer. A null property-value may be specified to request that the API returns the required buffer length to hold the specified property value.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-PROPERTY-NOT-FOUND
78-AUD-RET-BUFFER-TOO-SMALL
78-AUD-RET-VALUE-NOT-INTEGER
78-AUD-RET-EMITTER-NOT-FOUND

Comments:

CBL_AUDIT_EMITTER_PROPERTY_GET is used to retrieve a named property value for the emitter with name emitter-name. The function would typically by used by an emitter during its initialisation to determine how it had been configured.

Examples:

Get two property values associated with the "AUDITFILE" emitter: one a space-terminated string value, one an integer value.

copy "mfaudit.cpy ".

01 emitter-name    pic x(10) value " AUDITFILE".
01 flags           pic x(4) comp-5.
01 prop-integer    pic x(4) comp-5.
01 prop-len        pic x(4) comp-5.
01 prop-string     pic x(100).
...
compute flags = 78-AUD-FLAG-PROP-STRING-VALUE
move length of prop-string to prop-len

call "CBL_AUDIT_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "location "
                                    by reference prop-len
                                    by reference prop-string
...
compute flags = 78-AUD-FLAG-PROP-INT-VALUE

call "CBL_AUDIT_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "collectionsize "
                                    by value 0
                                    by reference prop-integer
...
Parent topic: Audit Event Consolidator APIs


CBL_AUDIT_EMITTER_PROPERTY_SET

Set an audit emitter property value.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_EMITTER_PROPERTY_SET" using by value     flags
                                            by reference emitter-name
                                            by reference property-name
                                            by reference property-value
                                               returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
emitter-name | pic x(n) | pic x(n)
property-name | pic x(n) | pic x(n)
property-value | pic x(n) | pic x(n)

On Entry:

flags
Bit | Value | Meaning
0 | 0 | String value. Use bit 1 to determine string terminator
1 | Integer value. Ignore bit 1.
1 | 0 | String value is space-terminated
1 | String value is null-terminated
2-27 | Reserved for future use (must be 0)
28 | 0 | emitter-name is space-terminated
1 | emitter-name is null-terminated
29 | 0 | property-name is space-terminated
1 | property-name is null-terminated
30-31 | Reserved for future use (must be 0)
emitter-name
Typedef: pic x(n)

Picture: pic x(n)

property-name
Typedef: pic x(n)

Picture: pic x(n)

property-value
Typedef: pic x(n)

Picture: pic x(n)

On Exit:

Nothing

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-EMITTER-NOT-FOUND
78-AUD-RET-INVALID-EMITTER-NAME
78-AUD-RET-INVALID-PROPERTY-NAME

Comments:

CBL_AUDIT_EMITTER_PROPERTY_SET is used to set a named property value for the emitter with name emitter-name. If a property with the same name already exists for the emitter, its value will be replaced with the new value.

Examples:

Set two property values associated with the "AUDITFILE" emitter: one a null-terminated string value, one an integer value.

copy "mfaudit.cpy ".

01 emitter-name    pic x(10) value "AUDITFILE".
01 flags           pic x(4) comp-5.
01 prop-integer    pic x(4) comp-5.
01 prop-string     pic x(100).
...
compute flags = 78-AUD-FLAG-PROP-STRING-VALUE b-or
                78-AUD-FLAG-PROP-NULL-TERM
move "xxx" & x"00" to prop-string

call "CBL_AUDIT_EMITTER_PROPERTY_SET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "location "
                                    by reference prop-string
...
compute prop-flags = 78-AUD-FLAG-PROP-INT-VALUE
move 10 to prop-integer

call "CBL_AUDIT_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "collectionsize "
                                    by reference prop-integer
...
Parent topic: Audit Event Consolidator APIs


Audit File Processing APIs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit File Processing APIs are available:

  • CBL_AUDIT_FILE_CLOSE
    Close an audit file.
  • CBL_AUDIT_FILE_OPEN
    Open an audit file.
  • CBL_AUDIT_FILE_READ
    Read a record from an audit file.
  • cobaudit_file_read
    Read a record from an audit file.
Parent topic: Audit Manager APIs


CBL_AUDIT_FILE_CLOSE

Close an audit file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_FILE_CLOSE" using by value     flags
                                  by value     auditfile-handle
                                     returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
auditfile-handle | cblt-pointer | pointer

On Entry:

Control flags

Bit | Value | Meaning
0 | 0 | Close all files associated with the handle
 | 1 | Close the current file associated with the handle (use when processing a file collection).
1 | 0 | Do not set 'dumped' flag
 | 1 | Set 'dumped' flag
2-31 |  | Reserved for future use (must be 0)
auditfile-handle
Audit handle returned by the CBL_AUDIT_FILE_OPEN API.

On Exit:

Nothing

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-INVALID-HANDLE
78-AUD-RET-FILE-NOT-DUMPED

Comments:

CBL_AUDIT_FILE_CLOSE() is used to close the audit file, or audit file collection, identified by the auditfile-handle parameter. The flags parameter can be used to control whether or not the file, or files if an audit file collection is associated with the handle, is marked as being 'dumped'. Once a file is marked as 'dumped', it can be reused by the audit event consolidator process.

Examples:

copy "mfaudit.cpy ".

01 auditfile-handle  pic x(4) comp-5.
01 flags             pic x(4) comp-5.
...
compute flags = 78-AUDITFILE-FLAG-CLOSE-CURRENT b-or
                78-AUDITFILE-FLAG-CLOSE-DUMPED

call "CBL_AUDIT_FILE_CLOSE" using by value flags
                                  by value auditfile-handle
...
Parent topic: Audit File Processing APIs


CBL_AUDIT_FILE_OPEN

Open an audit file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_FILE_OPEN" using by value     flags
                                 by reference auditfile-handle
                                 by reference auditfile-name
                                    returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
auditfile-handle | cblt-pointer | pointer
auditfile-name | pic x(n) | pic x(n)

On Entry:

flags
Bit | Value | Meaning
0 | 0 | Open the specified audit file
1 | Open the audit file collection for which the specified file is a member
1 | 0 | auditfile-name is space-terminated
1 | auditfile-name is null-terminated
2-31 | Reserved for future use (must be 0)

On Exit:

auditfile-handle Audit handle to be specified to the CBL_AUDIT_FILE_READ and CBL_AUDIT_FILE_CLOSE APIs.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-FILE-NOT-EXIST
78-AUD-RET-FILE-NOT-AVAILABLE
78-AUD-RET-FILE-INVALID-FORMAT
78-AUD-RET-FILE-INVALID-NAME

Comments:

CBL_AUDIT_FILE_OPEN() is used to open an audit file, or audit file collection. Only files that are available for dumping will be opened by this API (i.e. files in a collection which are marked as 'dumped' or 'active' will not be opened).

Examples:

copy "mfaudit.cpy ".

01 auditfile-handle  pic x(4) comp-5.
01 auditfile-name    pic x(32)
                     value "mfaudit.nwb-cpjdell.aud_1" & x"00".
01 flags             pic x(4) comp-5.
...
compute flags = 78-AUDITFILE-FLAG-OPEN-COLLECTION b-or
                78-AUDITFILE-FLAG-OPEN-NAME-NULL-TERM

call "CBL_AUDIT_FILE_OPEN" using by value flags
                                 by reference auditfile-handle
                                 by reference auditfile-name
      ...
Parent topic: Audit File Processing APIs


CBL_AUDIT_FILE_READ

Read a record from an audit file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_FILE_READ" using by value     flags
                                 by value     auditfile-handle
                                 by reference auditfile-record
                                    returning status-code

Parameters:

 | Typedef | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5
auditfile-handle | cblt-pointer | pointer
auditfile-record | cblt-aud-record | Group containing
cblte-audrec-version | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-flags | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-pid-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-tid-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-pid-32 | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-pid-64 | cblt-x8-comp5 | pic x(8) comp-5 redefines cblte-audrec-pid-32
cblte-audrec-tid-32 | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-tid-64 | cblt-x8-comp5 | pic x(8) comp-5 redefines cblte-audrec-tid-32
cblte-audrec-event-id | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-event-category | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-data-count | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-appname-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-cmdline-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-os-name-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-mc-name-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-sys-name-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-comp-name-len | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-encoded-time | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-hour | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-minute | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-second | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-millisecond | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-encoded-date | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-year | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-month | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-day | cblt-x4-comp5 | pic x(4) comp-5
cblte-audrec-reserved1 | cblt-x4-comp5 | pic x(4) comp-5 occurs 7
cblte-audrec-appname | cblt-pointer | pointer
cblte-audrec-cmdline | cblt-pointer | pointer
cblte-audrec-os-name | cblt-pointer | pointer
cblte-audrec-mc-name | cblt-pointer | pointer
cblte-audrec-sys-name | cblt-pointer | pointer
cblte-audrec-comp-name | cblt-pointer | pointer
cblte-audrec-event-len | cblt-pointer | pointer
cblte-audrec-event-type | cblt-pointer | pointer
cblte-audrec-event-data | cblt-pointer | pointer
cblte-audrec-reserved2 | cblt-pointer | pointer occurs 7

On Entry:

flags
Bit | Value | Meaning
0-31 | Reserved for future use (must be 0)
Auditfile-handle
Audit handle returned by the CBL_AUDIT_FILE_OPEN API.

On Exit:

cblte-audevt-version
Structure version
cblte-audevt-flags
Control flags
cblte-audrec-pid-len
Length of process identifier (4 or 8)
cblte-audrec-tid-len
Length of thread identifier (4 or 8)
cblte-audrec-pid-32
4-byte process identifier
cblte-audrec-pid-64
8-byte process identifier
cblte-audrec-tid-32
4-byte thread identifier
cblte-audrec-tid-64
8-byte thread identfier
cblte-audrec-event-id
Component specific audit event identifier
cblte-audrec-category
Audit event category
Value | Category
0 | Unknown
1 | Audit Facility
2 | System
3 | Security API request check
4 | Security API request define
5 | Security API request other
6 | Security API result allow
7 | Security API result deny
8 | Security API result error
9 | Security API result success
cblte-audrec-data-count
Number of audit data items. Indicates the number of items in the cblte-audrec-event-len, cblte-audrec-event-type and cblte-audrec-event-data arrays
cblte-audrec-appname-len
Length of application name
cblte-audrec-cmdline-len
Length of command line
cblte-audrec-os-name-len
Length of operating system name
cblte-audrec-mc-name-len
Length of computer/machine name
cblte-audrec-sys-name-len
Length of system name
cblte-audrec-comp-name-len
Length of component name
cblte-audrec-encoded-time
Encoded time of event
cblte-audrec-hour
Decoded hour
cblte-audrec-minute
Decoded minute
cblte-audrec-second
Decoded second
cblte-audrec-millisecond
Decoded millisecond
cblte-audrec-encoded-date
Encoded date of event
cblte-audrec-year
Decoded year
cblte-audrec-month
Decoded month
cblte-audrec-day
Decoded day
cblte-audrec-appname
Pointer to null-terminated name of application that generated audit event
cblte-audrec-cmdline
Pointer to null-terminated command-line of application that generated audit event
cblte-audrec-os-name
Pointer to null-terminated name of operating system that generated audit event
cblte-audrec-mc-name
Pointer to null-terminated name of computer that generated audit event
cblte-audrec-sys-name
Pointer to null-terminated name of system that generated audit event
cblte-audrec-comp-name
Pointer to null-terminated name of component that generated audit event
cblte-audrec-event-len
Pointer to array of 4-byte comp-5 items. Each array element indicates the length of the corresponding audit data item. Will be NULL if cblte-audrec-data-count is 0
cblte-audrec-event-type
Pointer to array of 4-byte comp-5 items. Each array element indicates the type of the corresponding audit data item in the cblte-audrec-event-data array. Will be NULL if cblte-audrec-data-count is 0.
Value | Type
0 | Binary
1 | Text (local encoding)
2 | Address
3 | COMP-5
4 | COMP-X
5 | UTF8
6 | Signed COMP-5
7 | Signed COMP-X

Any value other than the ones specified above will be treated as type 0 (binary).

cblte-audrec-event-data
Pointer to array of pointer items. Each array element addresses an audit data item of the type and length indicated by the corresponding element in the cblte-audrec-event-type and cblte-audrec-event-len arrays respectively. Will be NULL if cblte-audrec-data-count is 0.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-FAILURE
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-INVALID-HANDLE
78-AUD-RET-FILE-INVALID-FORMAT
78-AUD-RET-FILE-EOF
78-AUD-RET-FILE-NO-MORE-RECORDS

Comments:

CBL_AUDIT_FILE_READ() is used to return the next audit record from the file(s) associated with the current handle.

The function will return 78-AUD-RET-FILE-EOF when attempting to read past the last record in a file for the first time. The next attempt to read past the last record will either return the first record of the next file in the collection if a collection has been opened and another file is available, or 78-AUD-RET-FILE-NO-MORE-RECORDS.

Examples:

copy "mfaudit.cpy ".

01 auditfile-handle  pic x(4) comp-5.
01 auditfile-record  cblt-aud-record.
01 flags             pic x(4) comp-5.
...
compute flags = 0

call "CBL_AUDIT_FILE_READ" using by value flags
                                 by value auditfile-handle
                                 by reference auditfile-record
...
Parent topic: Audit File Processing APIs


cobaudit_file_read

Read a record from an audit file.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

cobrtncode_t cobaudit_file_read(cobuns32_t       flags,
                                cbl_os_pointer_t auditfile_handle,
                                AUDIT_RECORD     *auditfile_record)

On Entry:

Control flags
Bit | Value | Meaning
0-31 | Reserved for future use (must be 0)
auditfile-handle
Audit handle returned by the CBL_AUDIT_FILE_OPEN API.
auditfile_record
Audit event structure
version | Structure version (must be 0)
flags | Control flags (must be 0)

On Exit:

Auditfile_record

Audit event structure

version
Structure version
flags
Control flags
process_id_len
Length of process identifier (4 or 8)
thread_id_len
Length of thread identifier (4 or 8)
p.process_id_32
4-byte process identifier
p.process_id_64
8-byte process identifier
t.thread_id_32
4-byte thread identifier
t.thread_id_64
8-byte thread identfier
event_id
Component specific audit event identifier
event_category
Audit event category
Value | Category
0 | Unknown
1 | Audit Facility
2 | System
3 | Security API request check
4 | Security API request define
5 | Security API request other
6 | Security API result allow
7 | Security API result deny
8 | Security API result error
9 | Security API result success
data_count
Number of audit data items. Indicates the number of items in the event_len, event_type and event_data arrays
appname_len
Length of application name
cmdline_len
Length of command line
os_name_len
Length of operating system name
mc_name_len
Length of computer/machine name
sys_name_len
Length of system name
comp_name_len
Length of component name
time
Encoded time of event
hour
Decoded hour
minute
Decoded minute
second
Decoded second
millisecond
Decoded millisecond
date
Encoded date of event
year
Decoded year
month
Decoded month
day
Decoded day
appname
Pointer to null-terminated name of application that generated audit event
cmdline
Pointer to null-terminated command-line of application that generated audit event
os_name
Pointer to null-terminated name of operating system that generated audit event
mc_name
Pointer to null-terminated name of computer that generated audit event
sys_name
Pointer to null-terminated name of system that generated audit event
comp_name
Pointer to null-terminated name of component that generated audit event
event_len
Pointer to array of 4-byte comp-5 items. Each array element indicates the length of the corresponding audit data item. Will be NULL if data-count is 0
event_type
Pointer to array of 4-byte comp-5 items. Each array element indicates the type of the corresponding audit data item in the event_data array. Will be NULL if data_count is 0.

Any value other than the ones specified above will be treated as type 0 (binary).

Value | Type
0 | Binary
1 | Text (local encoding)
2 | Address
3 | COMP-5
4 | COMP-X
5 | UTF8
6 | Signed COMP-5
7 | Signed COMP-X
event_data
Pointer to array of pointer items. Each array element addresses an audit data item of the type and length indicated by the corresponding element in the event_type and event_len arrays respectively. Will be NULL if data_count is 0.

Return Codes:

AUDIT_RET_SUCCESS
AUDIT_RET_FAILURE
AUDIT_RET_INVALID_HANDLE
AUDIT_RET_NOT_ENOUGH_MEMORY
AUDIT_RET_FILE_INVALID_FORMAT
AUDIT_RET_FILE_EOF
AUDIT_RET_FILE_NO_MORE_RECORDS

Comments:

cobaudit_event() is intended for use by C programs. It is used to return the next audit record from the file(s) associated with the current handle.

The function will return AUDIT_RET_FILE_EOF when attempting to read past the last record in a file for the first time. The next attempt to read past the last record will either return the first record of the next file in the collection if a collection has been opened and another file is available, or AUDIT_RET_FILE_NO_MORE_RECORDS.

Parent topic: Audit File Processing APIs


Audit Emitter Interface

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Audit Emitter Interface information and APIs are available:

  • Audit Emitter Interface Overview
  • PFI_AUD_EMITTER_DEINIT
  • PFI_AUD_EMITTER_INIT
  • PFV_AUD_EMITTER_NOTIFY
  • PFI_AUD_EMITTER_OUTPUT
Parent topic: Audit Manager APIs


Audit Emitter Interface Overview

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Each emitter configured for use by the Audit Manager, whether well-known or dynamically loaded, will conform to the interface outlined in this section.

A dynamically loaded emitter is loaded by the Audit Manager using the program name specified by an mfaudit.emitter configuration file entry (see mfaudit.emitter.emitter-name).

Once loaded, the GET_AUDIT_EMITTER_FUNCS entry point of the loaded program is invoked to retrieve the address of a function pointer table (see Structures and Typedefs for AUDIT_EMITTER_FUNCS). This table contains pointers for a set of functions responsible for initialising the emitter, deinitialising the emitter, outputting an audit event, and handling notifications of emitter property changes. The example below shows how the main entry point for an emitter would typically be coded to return an AUDIT_EMITTER_FUNCS structure:

....
#include "mfaudit.h"
....
static int audit_emitter_deinit(cobuns32_t flags,
                                void       *emitter_data);

static int audit_emitter_init(cobuns32_t          flags,
                              const cobuns8_t     *emitter_name,
                              AUDIT_EMITTER_EVENT *audit_event,
                              void                **emitter_data);

static void audit_emitter_notify(cobuns32_t notif_type,
                                 void       *notif_buf,
                                 void       *emitter_data);

static int audit_emitter_output(cobuns32_t          flags,
                                AUDIT_EMITTER_EVENT *audit_event,
                                Void                *emitter_data);

static AUDIT_EMITTER_FUNCS audit_emitter_funcs =
{
    0,                         /* Version of structure format      */
    0,                         /* Reserved for future use          */
    audit_emitter_init,        /* Function to initialise the       */
                               /* emitter                          */
    audit_emitter_deinit,      /* Function to deinitialise the     */
                               /* emitter                          */
    audit_emitter_output,      /* Function to output a trace event */
    audit_emitter_notify,      /* Function to handle notifications */
                               /* of emitter config changes        */
};
....

AUDIT_EMITTER_FUNCS *
GET_AUDIT_EMITTER_FUNCS()
{
    return &audit_emitter_funcs;
}
....

Emitter initialisation (the invocation of the fn_init AUDIT_EMITTER_FUNCS function) is deferred by the Audit Manager until just prior to the first audit event needing to be output. During emitter initialisation the emitter would typically invoke the CBL_AUDIT_EMITTER_PROPERTY_GET API to pick up the value associated with each of its known properties.

Emitter de-initialisation (the invocation of the fn_deinit AUDIT_EMITTER_FUNCS function) occurs during Audit Manager de-initialisation. During emitter de-initialisation the emitter would release any resources it had acquired during any previous invocations.

The outputting of an audit event (the invocation of the fn_output AUDIT_EMITTER_FUNCS function) occurs when a component invokes the CBL_AUDIT_EVENT API (see CBL_AUDIT_EVENT() - Output an Audit Event).

The emitter is notified (the invocation of the fn_notify AUDIT_EMITTER_FUNCS function) of each configuration change (e.g. property value change) that occurs for it after it has been initialised.

Parent topic: Audit Emitter Interface


PFI_AUD_EMITTER_DEINIT

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef int (*PFI_AUD_EMITTER_DEINIT)(cobuns32_t flags,
                                      void       *emitter_data);

On Entry:

flags
Reserved for future use (must be 0)
emitter_data
Emitter-specific data

On Exit:

Nothing

Return Codes:

EMITTER_DEINIT_SUCCESS | 0
EMITTER_DEINIT_FAIL | -1

Comments:

This function is invoked by the audit facility during its deinitialisation to allow the emitter to release any resources it had acquired during any previous invocations.

Parent topic: Audit Emitter Interface


PFI_AUD_EMITTER_INIT

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef int (*PFI_AUD_EMITTER_INIT)(cobuns32_t          flags,
                                    const cobuns8_t     *emitter_name,
                                    AUDIT_EMITTER_EVENT *audit_event,
                                    void                **emitter_data);

On Entry:

flags
Reserved for future use (must be 0)
emitter_name
Name of emitter being initialised
audit_event
Details of the first audit event to be output. (N.B. the event is not expected to be emitted during initialisation, but the information provided may be useful for file header creation (e.g. date/time))

On Exit:

emitter_data
Emitter-specific data

Return Codes:

EMITTER_INIT_SUCCESS | 0
EMITTER_INIT_FAIL | -1

Comments:

This function is invoked by the audit facility to perform the emitter's initialisation. Initialisation would typically involve the interrogation of the audit facility for the emitter's configuration properties via calls to the CBL_AUDIT_EMITTER_PROPERTY_GET() API (see CBL_AUDIT_EMITTER_PROPERTY_GET() - Get an Audit Emitter Property Value).

Emitter initialisation is deferred by the audit facility until just prior to the first audit event needing to be output.

Parent topic: Audit Emitter Interface


PFV_AUD_EMITTER_NOTIFY

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef void (*PFV_AUD_EMITTER_NOTIFY)(cobuns32_t notif_type,
                                       void       *notif_buf,
                                       void       *emitter_data);

On Entry:

notif_type
Notification type:
0: Property value change has occurred. notif_buf is a pointer to an EMITTER_NOTIF_PROP_CHANGE structure.
notif_buf
Notification buffer. The contents of this buffer are dependent upon notif_type.
emitter_data
Emitter-specific data

On Exit:

Nothing

Return Codes:

Nothing

Comments:

This function is invoked by the audit facility for each configuration change that occurs for the emitter after it has been initialised.

Parent topic: Audit Emitter Interface


PFI_AUD_EMITTER_OUTPUT

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

typedef int (*PFI_AUD_EMITTER_OUTPUT)(cobuns32_t   flags,
                                      AUDIT_EMITTER_EVENT *audit_event,
                                      void		    *emitter_data);

On Entry:

flags | Reserved for future use (must be 0)
audit_event | Audit event to output
emitter_data | Emitter-specific data

On Exit:

Nothing

Return Codes:

EMITTER_OUTPUT_SUCCESS | 0
EMITTER_OUTPUT_FAIL | -1

Comments:

This function is invoked by the audit facility to output an audit event to an output destination.

Parent topic: Audit Emitter Interface


Structure and Typedefs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The following Structure and Typedefs APIs are available:

  • Structures and Typedefs for AUDIT_EMITTER_FUNCS
  • Structures and Typedefs - AUDIT_EVENT
  • Structures and Typedefs - AUDIT_EMITTER_EVENT
  • Structures and Typedefs - AUDIT_RECORD
  • Structures and Typedefs - EMITTER_NOTIF_PROP_CHANGE
Parent topic: Audit Manager APIs


Structures and Typedefs for AUDIT_EMITTER_FUNCS

Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct audit_event
{
    cobuns32_t                version;               Version of structure format
    cobuns32_t                reserved;	             Reserved for future use
    PFI_AUD_EMITTER_INIT      fn_init;               Function to initialise the emitter
    PFI_AUD_EMITTER_DEINIT    fn_deinit;             Function to deinitialise the emitter
    PFI_AUD_EMITTER_OUTPUT    fn_output;             Function to output a trace event
    PFV_AUD_EMITTER_NOTIFY    fn_notify;             Function to handle notifications of emitter config changes
    PFI                       fn_reserved[4];        Reserved for future use
} AUDIT_EMITTER_FUNCS;

Version types (version):

    #define AUDIT_EMITTER_FUNCS_VERSION	0
Parent topic: Structure and Typedefs


Structures and Typedefs - AUDIT_EVENT

Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct audit_event
{
    cobuns32_t	version;	Version of structure format
    cobuns32_t	flags;	Control flags
    cobuns32_t	event_id;	Audit event identifier
    cobuns32_t	event_category;	Audit event category
    cobuns32_t	data_count;	Number of audit data items
    cobuns32_t	reserved1[7];	Reserved for future use
    cobuns32_t	*event_len;	Audit data item lengths
    cobuns32_t	*event_type;	Audit data item types
    void	*event_data;	Audit data items
    void	*reserved2[7];	Reserved for future use
}AUDIT_EVENT;

Version types (version):

    #define AUDIT_EVENT_VERSION	0

Control flags (flags):

    #define AUDIT_EVENT_FLAGS_NONE	0x00000000

Audit event categories (event_category):

    #define AUDIT_EVENT_CATEGORY_UNKNOWN	0

Audit data item types (event_type):

    #define AUDIT_EVENT_TYPE_BINARY     0
    #define AUDIT_EVENT_TYPE_TEXT       1
    #define AUDIT_EVENT_TYPE_ADDRESS    2
    #define AUDIT_EVENT_TYPE_COMP5      3
    #define AUDIT_EVENT_TYPE_COMPX      4
    #define AUDIT_EVENT_TYPE_UTF8       5
    #define AUDIT_EVENT_TYPE_COMP5S     6
    #define AUDIT_EVENT_TYPE_COMPXS     7
Parent topic: Structure and Typedefs


Structures and Typedefs - AUDIT_EMITTER_EVENT

Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct audit_emitter_event
{
    cobuns32_t          version;          Version of structure format
    cobuns32_t          flags;            Control flags
    cobuns32_t          date;             Encoded date
    cobuns32_t          time;             Encoded time
    cobuns32_t          process_id_len;   Length of process identifier
    cobuns32_t          thread_id_len;    Length of thread identifier
    cobuns32_t          comp_id;          Component identifier
    cobuns32_t          event_id;         Audit event identifier
    cobuns32_t          event_category;   Audit event category
    cobuns32_t          data_count;       Number of audit data items
    cobuns32_t          reserved1[6];     Reserved for future use
    const cobuns8_t     *process_id;      Process identifier
    const cobuns8_t     *thread_id;       Thread identifier
    const cobuns8_t     *appname;         Null-terminated application name
    const cobuns8_t     *cmdline;         Null-terminated process cmd line
    const cobuns8_t     *os_name;         Null-terminated operating system name
    const cobuns8_t     *mc_name;         Null-terminated machine name
    const cobuns8_t     *sys_name;        Null-terminated system name
    const cobuns8_t     *comp_name;       Null-terminated component name
    const cobuns8_t     *auditmgr_name;   Null-terminated auditmgr instance name
    const cobuns32_t    *event_len;       Audit data item lengths
    const cobuns32_t    *event_type;      Audit data item types
    const void          **event_data;     Audit data items
    void                *reserved2[7];    Reserved for future use
}AUDIT_EMITTER_EVENT;

Version types (version):

    #define AUDIT_EMITTER_VERSION	0

Control flags (flags):

    #define AUDIT_EMITTER_FLAGS_NONE         0x00000000
    #define AUDIT_EMITTER_FLAGS_ARRAY_DATA   0x00000002

Event categories (event_category):

    #define AUDIT_EVENT_CATEGORY_UNKNOWN             0
    #define AUDIT_EVENT_CATEGORY_AUDIT_FACILITY      1
    #define AUDIT_EVENT_CATEGORY_SYSTEM              2
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_CHECK   3
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_DEFINE  4
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_OTHER   5
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_ALLOW   6
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY    7
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_ERROR   8
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_SUCCESS 9

Audit data item types (event_type):

    #define AUDIT_EMITTER_TYPE_BINARY     0
    #define AUDIT_EMITTER_TYPE_TEXT       1
    #define AUDIT_EMITTER_TYPE_ADDRESS    2
    #define AUDIT_EMITTER_TYPE_COMP5      3
    #define AUDIT_EMITTER_TYPE_COMPX      4
    #define AUDIT_EMITTER_TYPE_UTF8       5
    #define AUDIT_EMITTER_TYPE_COMP5S     6
    #define AUDIT_EMITTER_TYPE_COMPXS     7
Parent topic: Structure and Typedefs


Structures and Typedefs - AUDIT_RECORD

Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct audit_record
{
    cobuns32_t         version;                 Version of structure format
    cobuns32_t         flags;                   Control flags
    cobuns32_t         process_id_len;          Process identifier length (4 or 8 bytes)
    cobuns32_t         thread_id_len;           Thread identifier length (4 or 8 bytes)

    union
    {
    cobuns32_t            process_id_32;           Process identifier (32-bit)
    cobuns64_t            process_id_64;           Process identifier (64-bit)
    }p;

    union
    {
    cobuns32_t            thread_id_32;            Thread identifier (32-bit)
    cobuns64_t            thread_id_64;            Thread identifier (64-bit)
    }t;

    cobuns32_t         event_id;                Audit event identifier
    cobuns32_t         event_category;          Audit event category
    cobuns32_t         data_count;              Number of audit data items
    cobuns32_t         appname_len;             Application name length
    cobuns32_t         cmdline_len;             Process command line length
    cobuns32_t         os_name_len;             Operating system name length
    cobuns32_t         mc_name_len;             Machine name length
    cobuns32_t         sys_name_len;            System name length
    cobuns32_t         comp_name_len;           Component name length

    cobuns32_t         time;                    Encoded time
    cobuns32_t         hour;                    Decoded hour
    cobuns32_t         minute;                  Decoded minute
    cobuns32_t         second;                  Decoded second
    cobuns32_t         millisecond;             Decoded millisecond
    cobuns32_t         date;                    Encoded date
    cobuns32_t         year;                    Decoded year
    cobuns32_t         month;                   Decoded month
    cobuns32_t         day;                     Decoded day
    cobuns32_t         reserved1[7];            Reserved for future use

    const cobuns8_t    *appname;                Null-terminated application name
    const cobuns8_t    *cmdline;                Null-terminated process command line
    const cobuns8_t    *os_name;                Operating system name
    const cobuns8_t    *mc_name;                Machine name
    const cobuns8_t    *sys_name;               Null-terminated system name
    const cobuns8_t    *comp_name;              Null-terminated component name
    cobuns32_t         *event_len;              Audit data item lengths
    cobuns32_t         *event_type;             Audit data item types
    void               *event_data;             Audit data items
    void               *reserved2[7];           Reserved for future use
}AUDIT_RECORD;

Version types (version):

    #define AUDIT_RECORD_VERSION	0

Event categories (event_category):

    #define AUDIT_EVENT_CATEGORY_UNKNOWN             0
    #define AUDIT_EVENT_CATEGORY_AUDIT_FACILITY      1
    #define AUDIT_EVENT_CATEGORY_SYSTEM              2
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_CHECK   3
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_DEFINE  4
    #define AUDIT_EVENT_CATEGORY_SEC_API_REQ_OTHER   5
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_ALLOW   6
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_DENY    7
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_ERROR   8
    #define AUDIT_EVENT_CATEGORY_SEC_API_RES_SUCCESS 9

Audit data item types (event_type):

    #define AUDIT_EVENT_TYPE_BINARY    0
    #define AUDIT_EVENT_TYPE_TEXT      1
    #define AUDIT_EVENT_TYPE_ADDRESS   2
    #define AUDIT_EVENT_TYPE_COMP5     3
    #define AUDIT_EVENT_TYPE_COMPX     4
    #define AUDIT_EVENT_TYPE_UTF8      5
    #define AUDIT_EVENT_TYPE_COMP5S    6
    #define AUDIT_EVENT_TYPE_COMPXS    7
Parent topic: Structure and Typedefs


Structures and Typedefs - EMITTER_NOTIF_PROP_CHANGE

Restriction: This topic applies only when the Enterprise Server feature is enabled.
typedef struct emitter_notif_prop_change
{
    cobuns32_t           version;  Version of structure format
    cobuns32_t           flags;    Control flags
    cobuns32_t           namelen;  Length of property name
    cobuns32_t           vallen;   Length of value
    cobuns32_t           valint;   Integer representation of value
    cobuns8_t            *name;    Property name
    cobuns8_t            *value;   Property value
}EMITTER_NOTIF_PROP_CHANGE;

Version types (version):

    #define EMITTER_PROP_CHANGE_VERSION	0

Control flags (flags):

    #define EMITTER_PROP_CHANGE_FLAGS_NONE         0x00000000
    #define EMITTER_PROP_CHANGE_FLAGS_VAL_INTEGER  0x00000001
Parent topic: Structure and Typedefs


Securing Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.
Note: Before you attempt to secure communications, it is important that you understand PKI and SSL concepts. The SSL and PKI Technology Primer contains information on these concepts.
  • Introduction to Securing Communications
  • Configuring Secure Communications for Client Applications
  • Setting Up Secure Communications
  • Troubleshooting a Secure Connection
  • Using the Demonstration Certificate Authority
  • Tutorial: Requesting and Issuing Server Certificates
  • Tutorial: Configuring SSL Security in the Server
  • Information on OpenSSL
  • SSL and PKI Technology Primer
    The topics in this section describe the basics of SSL and PKI technology, and how they work together to secure communications.
  • Secure Communications (SSL) Legal Information
Parent topic: Enterprise Server Security


Introduction to Securing Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can enable secure communication between Micro Focus systems and clients who access those systems. This is done using Secure Sockets Layer (SSL) encryption. With secure communications, all communications between a client and a server are encrypted.

You typically use PKI certificates issued from a trusted Certifying Authority (CA) to secure your installation.

Web browser access is secured with the HTTPS web browser protocol. This mechanism secures web access, for example the Enterprise Server configuration user interface.

You can use the demonstration CA software to generate certificates and test your secure communications setup before using certificates issued by a trusted CA. The demonstration CA software is based on the OpenSSL software.

You can use these to familiarize yourself with the setup without the need to obtain cerrtificates from a trusted CA. The online help includes a tutorial that describes the process of using the DemoCA to secure your system.

Parent topic: Securing Communications


Configuring Secure Communications for Client Applications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A client application is an application that communicates with Enterprise Server Enterprise. You can require a certificate from any clients that communicate with your server. This sets up SSL links for peer-to-peer communication (as opposed to client/server communication).

In order to communicate securely, a client application needs access to the root certificates of any trusted CAs that the server uses. The trusted CAs are those who signed the certificates of the servers you are communicating with securely.

  • Securing Peer to Peer Communications
  • Installing a Client Certificate for Enterprise Server
  • Adding a CA Root Certificate to your Client Application
  • Installing a CA Root Certificate in a Client Browser
  • Installing server certificates for secure communication
Parent topic: Securing Communications


Securing Peer to Peer Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can configure that any clients that communicate with your server must supply a certificate. This sets up SSL links for peer-to-peer communication (as opposed to client/server communication)

To request or require a certificate from clients who communicate with your server:

  1. Connect to ES Admin, for example by entering http://localhost:86 in your Web browser.
  2. Select the enterprise server you want, such as ESDEMO. Stop it if it is started, and then click Edit.
  3. Go to the Listeners page.
  4. Select the HTTPS listener you want (if you can't see the one you want, set the Process filter to All), and click Edit .
  5. Check Secure Sockets Layer.
  6. Click SSL Options and then:
    • Check the appropriate option to request or require client certificates.
    • Enter the CA root certificate of the CA who signed the client cerificate.

If the CA who signed the client's certificate is not trusted, communication is prevented. If you want to trust the signing CA, you can add it to your trusted CAs by updating the relevant certificates options in your browser.

Parent topic: Configuring Secure Communications for Client Applications


Installing a Client Certificate for Enterprise Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

On client systems such as COBOL Web Services clients, and clients that use client/server binding, and COBOL XML I/O, you need to set client information in a file, as follows:

To set up client certificate, key file and pass phrase information in a file:

  1. On the Enterprise Server machine, create the file mf-client.dat in the $COBDIR/etc directory if the file doesn't already exist.
  2. Add an [SSL] section to this file and set parameters for the root certificate, the client certificate, the client key file, and the client key file passphrase, as follows:
         [SSL]
    root=/path/to/root/cert.type
    certificate=/path/to/client/cert.type
    key=/path/to/client/keyfile.type
    passphrase=keyfile passphrase

    where:

    • root defaults to ssldir/private/CArootcert.pem, where ssldir is the directory where Security Pack is installed, and is by default /opt/microfocus/DemoCA/openssl or $COBSSL (if set).
    • If certificate isn't specified, no client-side certificate is used
Note:
  • If you use a client certificate, the pass phrase for the key file appears in plain text in the mf-client.dat file. For security purposes, you should make this file readable only by the user or users who run applications that use this certificate.
  • Instead of mf-client.dat, you can create a file of any name or location, but you must identify it using the MFC_CONFIG environment variable.
Parent topic: Configuring Secure Communications for Client Applications


Adding a CA Root Certificate to your Client Application

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you have written a client application that communicates with server applications such as Enterprise Server, the client application needs access to the root certificates of any trusted CAs. The trusted CAs are those who signed the certificates of the servers you are communicating with securely.

This pack includes a collection of well-known CA root certificates plus the self-signed certificate of the demonstration CA. These root certificates are contained in a single file called CARootCerts.pem, found in /opt/microfocus/DemoCA/openssl or $COBSSL (if set) by default. This file is not protected by a pass phrase, so you can modify it. You need to add other CA root certificates to the CA root certificate file, if your client application communicates with servers whose certificates are signed by CAs whose certificates are not already in the file.

To add a CA root certificate to the root certificate file:

  1. Convert the new certificate to the same format as the certificates in the file, which in this case is PEM format with DER content encoding. Use openssl to do this. For example, to convert a PKCS7 format file, such as IECert.p7b, to PEM format:
    openssl pkcs7 -inform DER -in IECert.p7b -text -print_certs -out IECert.pem
  2. Append the new certificates to the existing file CARootCerts.pem. For example:
    cat CARootCerts.pem IECert.pem > NewCARootCerts.pem
Note: The CARootCerts.pem file is subject to being updated when a new version of the Micro Focus Security Pack is installed. If you add certificates to this file, you will need to repeat those additions when you update the Micro Focus Security Pack.
Parent topic: Configuring Secure Communications for Client Applications


Installing a CA Root Certificate in a Client Browser

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The root certificates of well-known trusted CAs are often installed with the client browser, so you might not need to install any. However, the security policy in your organization might restrict your access to the Web and might have removed the trusted CA root certificates. In this case you will need to install root certificates for the CAs that signed the server certificates of the servers you need to communicate with securely.

Note that the root certificate for the demonstration CA is not pre-installed, and so you need to install this certificate to enable you to use the demonstration CA.

CA root certificates can be specified as any of the following:

  • A single file containing a single certificate.
  • A single file containing multiple certificates. This file defines your trusted CAs (plus their chains if appropriate)
  • A directory containing PEM files that each contain a single certificate. These files are named with the hash value of the certificate content, using the hash.0 format. For example, you can display this hash value, using the command:
    openssl X509 -hash -in CARootcert.pem

    This produces the following output:

    1a584193
----BEGIN CERTIFICATE
....

    Where:

    • The number that is displayed before the certificate is the hash value of the certificate
    • The filename of the certificate would be 1a584193.0

To install a CA root certificate:

  1. In your browser, go to the options where you manage certificates. For example:
    • In Internet Explorer, click Tools > Internet Options > Content > Certificates. Go to the Trusted Root Certification Authorities tab.
    • In Mozilla Firefox, click Tools > Options > Advanced. Scroll down, click Manage Certificates and then click Authorities.
  2. Click Import and select the CA's root certificate.

    For the demonstration, select the self-signed certificate CARootCert.cer, which is in the private subdirectory of /opt/microfocus/DemoCA/openssl or $COBSSL (if set) by default.

    Internet Explorer requires X509 certificates, in DER format, so only those are listed in the File Open field, and not the PEM format files. Mozilla Firefox can handle several types, so several are listed and you can install the PEM-format certificate.

  3. In Internet Explorer, use the Browse button to enter Trusted Root Certification Authorities in the Certificate Store field.

    In Mozilla Firefox, check Trust this CA to identify Web sites.

  4. Look down the list under Trusted Root Certification Authorities (for Internet Explorer) and Authorities (for Firefox). You'll see your Demo CA is now listed; look for its Common Name. If when you installed Micro Focus Security Pack you chose to use your computer DNS name as the DemoCA's Common Name, it will probably look an odd-one-out, because real CAs tend to give themselves user-friendly Common Names.
Parent topic: Configuring Secure Communications for Client Applications


Installing server certificates for secure communication

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In the role of administrator of Enterprise Server, you need to install the SSL server certificate so that remote client software and Web users can request it. Installing a certificate entails storing the certificate and key file in a folder accessible to the server software.

To install a server certificate:

  1. Connect to ES Admin, for example by entering http://localhost:86 in your Web browser.
  2. Select the enterprise server you want, such as ESDEMO. Stop it if it is started, and then click Edit.
  3. Go to the Listeners page.
  4. Select the HTTPS listener you want (if you can't see the one you want, set the Process filter to All), and click Edit .
  5. If Secure Sockets Layer is not checked, check it and configure this listener as a secure listener.
  6. Enter the filenames of your server certificate and private key in the Certificate and Keyfile fields. If these are not in the default directories, you also need to supply the paths to these files. For example:
    • ssldir/certs/srvcert.pem
    • ssldir/keys/srvkey.pem

    Where ssldir is the directory where Security Pack is installed, and is by default /opt/microfocus/DemoCA/openssl or $COBSSL (if set).

  7. Click OK.
Parent topic: Configuring Secure Communications for Client Applications


Setting Up Secure Communications

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To set up secure communications, you need the following:

  • For machine on which the server operates, a certificate and a private key file for the server.

    Typically these are issued by a trusted Certifying Authority (CA). To set up secure communications, you need to know the path location where these files are stored.

  • The pass phrase for the server certificate and keyfile.
  • For machines that access the listener, the CA's root certificate.

    Root certificates for many trusted authorities are installed by default with many web browsers.

The process you use to set up secure communications for an Enterprise Server instance is outlined below:

  1. Install the certificate and a private key file on the machine running Enterprise Server, and note the path.
  2. For the Enterprise Server instance to configure, create a secure listener and configure it to use the key file that you installed.
  3. Start the server and the listener, and configure the private key file's pass phrases.

    You can set the certificate and keyfile pass phrases either in a configuration file, or you can enter them manually whenever you start the server.

  4. On machines that use the listener, if required, configure the CA root certificate.

Steps 2, 3, and 4 are described in detail in this help.

  • To enable secure communications with SSL
  • To configure an HTTPS listener
  • To Create a Secure Listener
  • To Start a Secure Listener and Set the Pass Phrase
  • To Configure the Pass Phrase in a File
Parent topic: Securing Communications


To enable secure communications with SSL

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. Make sure the enterprise server you're going to use, for example ESDEMO, is stopped.
  2. Create and configure an HTTPS listener.
  3. If you want to keep your pass phrases in a file, add them to the file.
  4. Return to the Home page of ES Admin and start ESDEMO.
  5. Check that all the listeners have started, by looking on the Listeners page. If you entered the pass phrases using a file, you should find that the HTTPS listener has started like all the other listeners. If you didn't, then the status of the HTTPS listener is Start pending.
  6. If you didn't set the pass phrase using a file, set it now:
  7. Optionally, enable additional logging of listener startup for debugging purposes.
Parent topic: Setting Up Secure Communications
Related information
To configure an HTTPS listener
To enable logging for listener startup


To configure an HTTPS listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.

As a Web site owner or administrator of Enterprise Server, to ensure secure communcation using SSL, you create and configure an HTTPS listener, as follows:

  1. Connect to ES Admin, for example by entering http://localhost:86 in your Web browser. Make sure the enterprise server you're going to use, for example ESDEMO, is stopped.
  2. Go to the Listeners page and find your HTTPS listener. The status column should indicate "Start pending" and the Status Log column shouold show "Waiting for keyfile passphrase".
  3. Go to the listeners page, (click Edit > Listeners). Make sure the Process filter is set to All so you can see all the listeners.
  4. Click Add.
  5. Enter a name for the listerner.
  6. Change the Endpoint Address to *.443, which is the default for HTTPS.
  7. Check Secure Sockets Layer.
  8. Enter the filenames of your server certificate and private key in the Certificate and Keyfile fields. If these are not in the default directories, you also need to supply the paths to these files. For example:
    • ssldir/certs/srvcert.pem
    • ssldir/keys/srvkey.pem

    Where ssldir is the directory where Security Pack is installed, and is by default /opt/microfocus/DemoCA/openssl or $COBSSL (if set).

  9. Specify that this will be an "HTTP echo" listener, which provides a simple response to HTTP requests. To do this, select Custom under Supported Conversation Type and enter http-echo in the field alongside.
  10. Click Add. On the listeners page, the new listener now has a padlock symbol to show that it uses SSL.
Parent topic: Setting Up Secure Communications


To Create a Secure Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For an Enterprise Server instance, you can create a secure listener, to encrypt the communications that the listener handles.

  1. On the Enterprise Server Administration screen, edit the server to which you want to add the secure listener.
  2. Select the Listeners tab, and next to the listener you want to secure, click Edit.
  3. In the Endpoint Options area, select the Secure Sockets Layer checkbox.

    The Certificate and the Keyfile fields become active.

  4. Enter the path locations of the certficate and the private key file.
  5. Click OK to save your configurations.
Parent topic: Setting Up Secure Communications


To Start a Secure Listener and Set the Pass Phrase

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You use this task for Enterprise Server instances with secure listeners where you want to set the pass phrases each time you start the server.

  1. On the Enterprise Server Administration screen, click the Start button for the server that you want to start, and on the confirmation screen, click OK to continue.
  2. When the server starts, click the server's Details button.
  3. On the server's Details screen, select the Listeners tab.
  4. In the listener list, locate your secure listener, and in the Status column, click Authorize.

    The Communications Process screen is displayed.

  5. Enter the Certificate Passprhase and the Keyfile Passphrase and click Set Passphrases The passphrases are set and the listener starts and becomes available for use.
Note: If the listener fails to start, it can be useful to look in the CS console. To access the CS console, on the server's Details page, select: Server > Diagnostics > CS Console
Parent topic: Setting Up Secure Communications


To Configure the Pass Phrase in a File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can configure the pass phrases that a listener requires in the mf-server.dat file. When you start the listener, it retrieves the passphrases from the file, and you do not need to configure them manually.

The mf-server.dat file is in the $COBDIR/etc directory by default.

  1. Open the mf-server.dat file in a text editor.
  2. In the file, add the following lines:
    [Listener-name/SSL/passphrases]
certificate=certificate passphrase
keyfile=keyfile passphrase
    where:
    • Listener-name is the name of the listener.
    • certificate passphrase is the certificate's passphrase.
    • keyfile passphrase is the keyfile's passphrase.
  3. Save the file and start the listener. The listener retrieves the passphrases from the file and starts.
Note:

The pass phrases appear in plain text in the mf-server.dat file. For security purposes, you should make this file readable only by the user account (or accounts) under which the enterprise server is started. That would normally be the account under which Micro Focus Directory Server (MFDS) runs (typically LOCAL_SYSTEM) and the accounts of any users who run casstart from the command line.

Parent topic: Setting Up Secure Communications


Troubleshooting a Secure Connection

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If a secure listener fails to start, there are some options you can use to locate the cause.

  • Accessing the Communications Server Console
  • To Enable Logging for Listener Startup
  • Locating Certificate Problems
Parent topic: Securing Communications


Accessing the Communications Server Console

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To determine the cause of a secure listnener failure, it can be useful to look in the Communications Server (CS) console and review the messages that the listener generated. To access the CS console:

  1. On the Entereprise Server Administration Home page, click Edit at the left of the server you want to check.
  2. Click the Diagnostics tab, then click the CS Console tab.
  3. To view the entire log since the server was started, click Show Entire Log. The log opens in a text editor window.
Parent topic: Troubleshooting a Secure Connection


To Enable Logging for Listener Startup

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To help locate the causes of listener problems, you can enable additional logging of the listener startup process.

  1. On the Entereprise Server Administration Home page, click Edit at the left of the server you want to configure
  2. Go to the Listeners page.
  3. At the top of the list of listeners, click the Communications Process Edit button (not Edit for any of the inidividual listeners).
  4. Add the following to the Configuration Information area:
    [listeners]
logging=3
  5. Click OK.

LIstener startup information is now logged, and is available in the log files.

Parent topic: Troubleshooting a Secure Connection


Locating Certificate Problems

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your application refuses to trust a certificate from a specific location, it might be because the one of the signers in the chain of CAs, or even the originating CA root, is not trusted. To locate the problem, you need to get the server's certificate chain, from its own identity certificate right through to the originating CA root in the server's chain of trust.

To get the chain of certificates for a specific server, you use the s_client function of OpenSSL. This function implements a generic SSL/TLS client that can establish a transparent connection to a remote server speaking SSL/TLS. It's intended for testing purposes only and provides only rudimentary interface functionality but internally uses mostly all functionality of the OpenSSL ssl library.

You connect to a SSL service on the server, as follows:

openssl s_client -showcerts -connect <myserver>:<ssl_port>

This returns all the certificates in the chain, starting with the server certificate and ending with the root CA certificate. They are all in PEM format. This command opens a session with the server. After responding to your request for the certificates, the session sits waiting for you to send further requests. You can send Ctrl+Z to exit the session or wait for the server to time out the connection.

For example:

openssl s_client -showcerts -connect ibank.myBank.co.uk:443

The above command returns:

Loading 'screen' into random state - done
CONNECTED(00000790)
depth=2 /C=US
        /O=VeriSign, Inc.
        /OU=Class 3 Public Primary Certification Authority

verify error:num=19:self signed certificate in certificate chain
verify return:0

Error 19 status is expected, because the CA root certificate in all certificate chains is self-signed. See Error 19 Details later for more details.

---
Certificate chain
 0 s:/C=GB/ST=Bucks/L=Chesham/O=myBank PLC
     /OU=Enable
     /OU=Terms of use at www.verisign.co.uk/rpa (c) 03
     /OU=Authenticated by VeriSign
     /OU=Member, VeriSign Trust Network
     /CN=ibank.myBank.co.uk
   i:/O=VeriSign Trust Network
     /OU=VeriSign, Inc.
     /OU=VeriSign International Server CA - Class 3
     /OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign
-----BEGIN CERTIFICATE-----
MIIE3TCCBEagAwIBAgIQXM1dOQs/cV03UDAru58mEjANBgkqhkiG9w0BAQQFADCB
ujEfMB0GA1QBChMWVmVyaVNpZ24gVHJ1c3QgTmV0d29yazDJEEUGA1UECxMOVmVy
ONfYgdrkI7Bwhc58KJR4zqwppdl0QgsspXgmz7gJFgsgfZdptm/QvXfs+N4mxDm8
b0I6p9RtmLq82Itr6q1wUWssjHm5PlZRoQ8YaYJkaUN2rLsRT1SyQxygRo9xu81d
0Q==
-----END CERTIFICATE-----

This marks the end of certificate “0”, which identifies the server system. The next section labeled "s:" refers to the certificate owner ("subject") and the following section "i:" refers to the issuer.

 1 s:/O=VeriSign Trust Network
     /OU=VeriSign, Inc.
     /OU=VeriSign International Server CA - Class 3
     /OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign
   i:/C=US
     /O=VeriSign, Inc.
     /OU=Class 3 Public Primary Certification Authority
-----BEGIN CERTIFICATE-----
MIIDgzCCAuygAwIBAgIQJUuKhThCzONY+MXdriJupDANBgkqhkiG9w0BAQUFADBf
MQswCQYDVQQGEwJVUzEXMBUGA1UEChMOVmVyaVNpZ24sIEluYy4xNzA1BgNVBAsT
1RPuKSvD5HKNRO3RrCAJLeH24RkFOLA9D59/+D3R3IYChmFOJl9en5IeDCSk9dBw
E88mw0M9SR2egi5SX7w+xmYpAY5Okiy8RnUDgqxz6dl+C2fvVFIa
-----END CERTIFICATE-----

We have reached the end of certificate “1” which identifies the signer of the server system’s certificate. Looking at the “s” section we can see that there is less detail in this certificate than in certificate “0”, but still enough to give a legal identity to the signer. This is important to understand. When creating certificate to use in real world situations, the creator must provide enough information within the certificate content to legally identify the item or entity being represented by the certificate.

 2 s:/C=US
     /O=VeriSign, Inc.
     /OU=Class 3 Public Primary Certification Authority
   i:/C=US
     /O=VeriSign, Inc.
     /OU=Class 3 Public Primary Certification Authority
-----BEGIN CERTIFICATE-----
MIICPDCCAaUCEHC65B0Q2Sk0tjjKewPMur8wDQYJKoZIhvcNAQECBQAwXzELMAkG
A1USXhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTcwNQYDVQQLEy5DbGFzlbwdj2wsqFHMc9ikwFPwTtYmwHYBV4GSXiHx0bH/59AhWM1pF+NEHJwZRDmJXNyc
AA9WjQKZ7aKQRUzkuxCkPfAyAw7xzvjoyVGM5mKf5p/AfbdynMk2OmufTqj/ZA1k
-----END CERTIFICATE-----
---
Server certificate
subject=/C=GB/ST=Bucks/L=Chesham/O=myBank PLC
        /OU=Enable
        /OU=Terms of use at www.verisign.co.uk/rpa (c) 03
        /OU=Authenticated by VeriSign/OU=Member, VeriSign Trust Network
        /CN=ibank.myBank.co.uk
issuer=/O=VeriSign Trust Network
       /OU=VeriSign, Inc.
       /OU=VeriSign International Server CA - Class 3
       /OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign
---
No client certificate CA names sent
---
SSL handshake has read 2894 bytes and written 352 bytes
---
New, TLSv1/SSLv3, Cipher is RC4-MD5
Server public key is 1024 bit
SSL-Session:
    Protocol  : SSLv3
    Cipher    : RC4-MD5
    Session-ID: 56931DEEE4EDB5808FAC374D3AD7EC1C90A4FB4E2FF6DA16749203A87C7FA169

    Session-ID-ctx:
    Master-Key: C87463A6C17BFC2A8817F9B6B302C8EAE53B2BC25AB63A3DEA461EA495B20C78
B4AAF17DEED14661D8A09488215DCA7B
    Key-Arg   : None
    Start Time: 1112711406
    Timeout   : 300 (sec)
    Verify return code: 19 (self signed certificate in certificate chain)
---
closed

You can close the session using Ctrl+Z and then Enter, to which the server should respond:

DONE

Error 19 Details

In the above example, you can see that the ultimate CA root certificate is self-signed. The ultimate CA root certificate in all certificate chains is self-signed.

The error 19 occurs because the s_client function doesn't check the default OpenSSL CA certificate store against the CA root certificates being passed in the replies by the server. So, even if this certificate is already present in the CARootCerts file, and this file is correctly configured in the openssl.cnf file, this function will still fail to trust the self-signed certificate.

You can avoid this error by setting up a collection of trusted CA root certificates to be used in this s_client function call. This makes the s_client function check the default OpenSSL CA certificate store against the CA root certificates being passed in the replies by the server.

To avoid generating the error 19 from s_client, the caller must pass one of the following arguments:

  • -CApath <ssl-base-dir>certs/ to use a directory of CA root certificates
  • -CApath <ssl-base-dir>file to use a single file certificate collection of your choice which would contain all the trusted certificates for the PKI within which your installation is operating
Parent topic: Troubleshooting a Secure Connection


Using the Demonstration Certificate Authority

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes the demonstration Certificate Authority (CA), delivered as part of Micro Focus Security Pack.

You can use the demonstration CA software to generate certificates and test your secure communications setup before using certificates issued by a trusted CA. The demonstration CA software is based on the OpenSSL software.

You can familiarize yourself with the setup without the need to obtain cerrtificates from a trusted CA. The online help includes a tutorial that describes the process of using the DemoCA to secure your system.

  • About the Demo CA
  • OpenSSL and Micro Focus Demo CA
  • Installing Micro Focus Demo CA
  • Contents of the Demonstration CA
  • Your CA Certificate, Key and Password
  • Your Distinguished Name and Policy
  • Is the Demonstration CA a Real CA?
Parent topic: Securing Communications


About the Demo CA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Micro Focus Demo CA enables you to configure secure communication for an Enterprise Server listener.

Encryption uses Secure Sockets Layer (SSL) and is fully interoperable with standard (non-Micro Focus) SSL clients and servers. Micro Focus Demo CA also provides support for integration with Public Key Infrastructures (PKIs) and PKI functions, such as processing certificates.

The demonstration CA software enables you to operate as a Certifying Authority. An operating CA needs to create certificates, and it needs an LDAP to store the certificates it creates along with its own certificate (self-signed in the case of a root CA). For training and testing you will be acting as both a CA and a server requesting certificates, so you need certificates and keys for both.

The demonstration CA comprises a directory structure and the files needed for the demonstration. The demonstration CA is set up with the following:

  • A public/private key pair.
  • A certificate containing your Distinguished Name, your public key and signed with your private key. The Distinguished Name comprises the details you gave during installation, such as your computer name (known as Common Name in PKI terminology), address, and so on.
  • A pass phrase, which you use to access the private key. This pass phrase is srvrootpwd, which you can change later. OpenSSL uses pass phrases, which can include spaces, whereas passwords cannot.
  • A configuration file openssl.cnf, which contains the SSL defaults and other information.

You use the demonstration CA to create certificates. Since the CA is local, these certificates are not recognized outside your organization. For production use you should obtain certificates from a well-known Certifying Authority and use those. The Demo CA is suitable for training and testing.

Note:

If you consider using the demonstration for anything other than training or testing, it is essential that you read the warnings in the section Is the Demonstration CA a Real CA?.

Parent topic: Using the Demonstration Certificate Authority
Related information
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


OpenSSL and Micro Focus Demo CA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Micro Focus Demo CA includes the utility openssl.exe. You can use the demonstration CA to generate and process certificates and keys during training, development and testing.

OpenSSL is an organization that has developed a toolkit for implementing SSL. A subset of this toolkit is provided with this pack, as a command-line utility called openssl.exe. It provides functions you need for using SSL and PKIs - notably, functions for creating and checking certificates. For details on the OpenSSL organization, see their Web site www.openssl.org.

The SSL support in the Micro Focus Demo CA is based on the OpenSSL source distribution, and provides a subset of the features in full OpenSSL source. Therefore, documentation on the Web regarding OpenSSL applies to the SSL support provided by this pack, although some features might not be relevant. The SSL documentation on the Web can be a useful guide.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


Installing Micro Focus Demo CA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

By default, the Micro Focus Demo CA installation file, DemoCA_Setup.sh is located in /opt/microfocus/DemoCA/openssl or $COBSSL (if set).

To install Micro Focus Demo CA:

  1. Make sure that Visual COBOL is installed on the installation machine.
  2. Use the following command to run the installable shell script DemoCA_Setup.sh:
    sh DemoCA_Setup.sh
Note: The values that you set in the installation screen define the default distinguished name (DN) for the sample certificates created in the DemoCA.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


Contents of the Demonstration CA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Demo CA installation creates the following directories and contents:

Name | Description
certs | You use this directory to store copies of all certificates and key files that you as a CA issue
crl | When you revoke a certificate, it is added to file crl.pem in here
newcerts | Holds the database of certificates you have issued. When you create a certificate, it is created in here with a numeric name, for example 01.pem.
private | Contains your self-signed CA root certificate in several formats and your private key

The following files are installed by default in /opt/microfocus/DemoCA/openssl or $COBSSL (if set):

Name | Description
create_srv_req.cmd | Script that creates a request for a server certificate
create_cli.cmd | Script that creates a client certificate
index.txt | Index to the certificates stored in newcerts
install_demoCA.cmd | Script that creates a CA that can be used to sign and verify certificates. This is for demonstration and development purposes only and should not be used in production.
sign_srv.cmd | Script that processes a server certificate request and signs the certificate
openssl.exe | OpenSSL command-line utility
openssl.cnf | Configuration file that specifies directories and defaults for SSL support
.rand | Random number used in generating keys. This number is generated anew each time you create a key.
serial | Number to be allocated to the next certificate you issue.
srv.pem | Certificate request (together with the private key in the one file) from which the server certificate was created
srvcert.pem | Your server certificate
srvkey.pem | Your server's private key
Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


Your CA Certificate, Key and Password

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The private subdirectory contains the root CA certificate and matching private key.

The certificate is provided in several formats, because different entities that you communicate with, such as different browsers, may require different formats. The .pem files contain a format called PEM. This is a way of modifying a binary string so that the bit pattern in each byte coincides with an ASCII character, so that the string is printable and displayable as text. The .cer file contains a format called DER, which is not plain text.

The files provided in the private subdirectory are:

  • CAkey.pem - the CA's private key file. You can open this file in a text editor and see that the key is just one long number. In PEM format, it is preceded and followed by headers - these identify it as an RSA private key. It has been encrypted, by combining it with the pass phrase mentioned above. It appears as a string of characters.
  • CARootcert.pem - the CA's certificate in PEM format, the default for OpenSSL. In a text editor, the PEM-format certificate looks similar in layout to the key, but in fact a certificate has a complex structure. You can open the certificate file using the x509 command of the openssl utility. For example from the private subdirectory, enter:
    ..\openssl x509 -in carootcert.pem -text

    This shows the certificate first in human-readable form, and then in machine-readable form between the BEGIN CERTIFICATE and END CERTIFICATE lines. It shows that the public key was generated using the RSA algorithm and is 1024 bits long. The signature was created using the MD5 hashing algorithm and the RSA encryption algorithm. Notice that the Issuer and Subject are the same, because this is a self-signed certificate, as you would expect of a root CA's certificate.

  • CARootcert.cer - The CA's certificate in another format, P7B format, the default for Internet Explorer, which might be required because different browsers require different formats. You can view the certificate using the x509 command and the -inform parameter to specify that this certificate is in DER format. For example from the private subdirectory, enter:
    ..\openssl x509 -in carootcert.cer -text -inform DER

    Compare the x509 displays of the PEM and DER versions of this certificate, and notice that their contents are identical. However, you cannot display the DER one with a text editor.

The CAKey.pem and srvkey.pem files are installed with the same password "srvrootpwd". See Is the Demonstration CA a Real CA? for recommendations.

You should regard the contents of this private folder as sacrosanct. These are the public/private key pair that you must have in order to operate your CA. Do not alter or lose anything in here. Note that anyone who gets hold of your private key can masquerade as you. In production, you would take precautions such as making these files read-only, and keeping secure backups.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your Distinguished Name and Policy
Is the Demonstration CA a Real CA?


Your Distinguished Name and Policy

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When you installed the Micro Focus Security Pack, you provided details of your site, such as Common Name, locality, and so on. All these details together are known as your Distinguished Name, and are intended to identify your site uniquely in the world. These details were put into your certificates.

Especially important is the Common Name. If this is not exactly the same as the fully qualified domain name of the machine running your SSL software, people you communicate with will get warnings that your certificate may not be valid. This field defaults to the name as known to your operating system, so you will probably not need to change it. You can however use wildcards in the Common Name, so you can use the same certificate for several machines. You will need to do this if, for example, you are running a Web site with a cluster of Web servers.

The elements of the Distinguished Name - Common Name, Locality, and so on - are standard, but it's up to you as the CA to have a policy on which of them you require. You can define the policy and specify the required elements, using the policy directive of the openssl ca function. You can specify several default groups of content within openssl.cnf and refer to each group by its name as a policy. See OpenSSL Configuration File.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Is the Demonstration CA a Real CA?


Is the Demonstration CA a Real CA?

Restriction: This topic applies only when the Enterprise Server feature is enabled.
CAUTION:

We strongly recommend that you do not use the demonstration CA to set up a commercial CA or other generally available CA service.

If you intend to set up a PKI within your organization, the demonstration CA is suitable software to use to run your real-life CAs. However, Micro Focus does not provide support for this use. As with any production software system, you must take great care to back up vital information and keep it secure.

The demonstration CA is suitable for creating certificate signing requests to be sent to a commercial or official CA.

Note:

The demonstration CA is installed with the same password "srvrootpwd" for the CA root private key CAkey.pem and the server private key Srvkey.pem files. We recommend that to ensure any form of real security you regenerate the demonstration CA content and recreate a server certificate.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Installing Micro Focus Demo CA
Contents of the Demonstration CA
Your CA Certificate, Key and Password
Your Distinguished Name and Policy


Tutorial: Requesting and Issuing Server Certificates

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This tutorial shows how to request and issue server certificates, using the scripts supplied with the demonstration CA.

  • Introduction
  • Requesting a Server Certificate
  • Issuing a Server Certificate
Parent topic: Securing Communications


Introduction

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this tutorial, you first request a server certificate from the CA. Then you take the role of the CA and issue the requested certificate. To do this, you use the following scripts:

  • create_srv_req.cmd creates a request for a server certificate, using the OpenSSL command openssl req. It creates a public/private key pair for your server, putting the public key in a certificate request, which you subsequently send to the CA.
  • sign_srv.cmd, which processes a server certificate request created with the above script, and signs it using the openssl ca command. It creates a signed certificate, which containing the public key from the certificate request.

These scripts are supplied with Micro Focus Demo CA and are by default in /opt/microfocus/DemoCA/openssl or $COBSSL (if set).

Parent topic: Tutorial: Requesting and Issuing Server Certificates
Related information
Requesting a Server Certificate
Issuing a Server Certificate


Requesting a Server Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this section, you ask the certifying authority (CA) for a server certificate. As the server owner you create a private key and a public key. The public key is created in a certificate request (usually called a Certificate Signing Request, CSR) that you would send to the CA.

With a commercial CA, you would typically contact them first, learn about what types of certificates they supply, and find out their prices, terms and conditions.

  1. Run the batch utility create_srv_req.cmd, located in /opt/microfocus/DemoCA/openssl or $COBSSL (if set) by default.

    The batch file creates a public/private key pair for your server, and creates a certificate request with the public key, to send to the CA.

    The private key is generated first and is stored in srvkey.pem.

  2. At the prompt, enter a pass phrase. Use a pass phrase that is easy for you to remember and yet hard for others to guess, for example: open sesame You must supply this pass phrase to access your server's private key. You are prompted to confirm the pass phrase.
  3. The utility prompts you for the following details. These default to the values that you entered when you installed Micro Focus Demo CA:
    • Country Name
    • State or Province
    • Locality
    • Organization Name
    • Organizational Unit
    • Common Name

    For example, you can enter something like:

    Country Name: US
State or Province Name: California
Locality: Palo Alto
Organization Name: Bloggs Widgets Inc
Organizational Unit Name: Marketing
Common Name: [Press Enter to accept
the server name value configured on installation.]
Email Address: bloggs@widgets.com

    The details you enter are included in your server certificate to identify you.

  4. At the Enter an additional challenge password prompt, press Enter to ignore it. You can specify a pass phrase to protect your public certificate, but since it is a public certificate, it is seldom appropriate to protect it in this way.
  5. At the Unstructured Name prompt, press Enter to ignore.
  6. When the batch file finishes, confirm that the following were created in the installation directory:
    • Your server's private key in srvkey.pem. You can view this in a text editor.
    • Your public key in a certificate request file called srvcertreq.csr. The CSR file is formatted according to the PKCS #10 standard, and is informally known as a PKCS #10 file, P10 file, or CSR file. You can view this using the req as follows:
      openssl req -in srvcertreq.csr -text
  7. In a real case you would now send srvcertreq.csr to the CA.
Parent topic: Tutorial: Requesting and Issuing Server Certificates
Related information
Introduction
Issuing a Server Certificate


Issuing a Server Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this section, you issue the server certificate.

  1. Run the batch file sign_srv.cmd, which is in /opt/microfocus/DemoCA/openssl or $COBSSL (if set) by default. When the batch file asks if you ready, press any key.

    The batch file calls the ca command of the openssl utility to create a signed certificate, srvcert.pem, containing the public key from the certificate request.

  2. When you are prompted for the passphrase, enter the CA passphrase srvrootpwd. This confirms your right to access the CA private key file cakey.pem, and then displays the certificate request (from the CSR file srvcertreq.csr).
  3. When asked whether to sign the certificate, reply y twice.

    The certificate is then created and signed with your private key from cakey.pem. It is in PEM format. It is saved in srvcert.pem, with a copy in newcerts\01.pem. If this tutorial has been run before, and 01.pem already exists, the copy will be called 02.pem and so on.

  4. As before, view the certificate using the openssl x509 command:
    openssl x509 -in 01.pem -text

    Notice that the Issuer is shown as the Distinguished Name of your Demo CA, while the Subject - the entity to whom the certificate has been issued - is the Distinguished Name of your server.

  5. Copy 01.pem from the newcerts directory to the certs, which is your Demo CA's database of certificates it has issued.
  6. In a real case the CA would now send srvcert.pem to the server owner to install it in their SSL software so that Web users can download it.
Parent topic: Tutorial: Requesting and Issuing Server Certificates
Related information
Introduction
Requesting a Server Certificate


Tutorial: Configuring SSL Security in the Server

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This tutorial shows how to configure SSL security in Enterprise Server.

  • Introduction
  • Creating a Secure HTTPS Listener
  • Installing the Server Certificate
  • Setting a Pass Phrase
  • Interpreting a Security Alert
  • Importing the CA's Root Certificate
  • Verifying the Certificate
  • Tidying Up
Parent topic: Securing Communications


Introduction

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this tutorial:

  • As the server administrator, you configure SSL security for Enterprise Server.

    You create an HTTPS listener and you install the server certificate and private key file that you created in the previous tutorial.

  • As an Enterprise Server user, you connect to the server from a Web browser. You install the CA's root certificate in order to access Enterprise Server.

    Typically, you rarely need to install CA root certificates. These are already configured for most trusted Certifying Authorities.

Note:

You must have completed the previous tutorial, Requesting and Issuing Server Certificates before you can run this tutorial.

In this tutorial, you configure the ESDEMO server to use secure communications. ESDEMO is created by the Enterprise Server installation. Within an enterprise server, you can create listeners for different kinds of communication.

One of ESDEMO's default listeners is HTTP Echo. This listener provices a simple test of Web communication. When a Web browser connects to HTTP Echo, the listener responds by sending a simple Web page with some identifying details.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Creating a Secure HTTPS Listener

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This section describes the process that the server owner uses to configure an enterprise server to use SSL. In this tutorial, you create an HTTPS version of the HTTP Echo listener. You will use this listener in the stage: Interpreting a Security Alert

  1. Start Enterprise Server Administration, access the Home screen and make sure the ESDEMO enterprise server is stopped.
  2. For ESDEMO, click Edit > Listeners to access the Listeners page. Make sure the Process filter is set to All so you can see all the listeners.
  3. Click Add to create a listener for HTTPS.
  4. In the Name field, enter HTTPS Echo as the name.
  5. Change the Endpoint Address to *.9443.

    Although you can use port 443, it might already be in use. For example, IIS listens by default on port 443. If you want to use port 443, you can check whether it is in use, by running the following command:

    netstat -an | findstr 443
  6. Specify that this will be an "HTTP echo" listener, which provides a simple response to HTTP requests. To do this, select Custom under Supported Conversation Type and enter http-echo in the field alongside.
  7. In the Description field, type:
    Simple secure HTTP test
  8. Click Add.

On the Listeners page, the new entry for HTTP Echo appears.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Installing the Server Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this section, as server administrator, you install the server certificate on the server so that remote Web users can to request it. To install a certificate, you store the certificate and the key file in a folder accessible to your server software.

  1. Edit the new HTTPS Echo listener. To do this, select the new listener on the Listeners page and click Edit.
  2. Check Secure Sockets Layer.
  3. Enter the full path and filenames of your server certificate and private key in the Certificate and Keyfile fields. These are by default srvcert.pem and srvkey.pem, installed by default in /opt/microfocus/DemoCA/openssl or $COBSSL (if set).
  4. Click OK.

    On the Listeners page, the entry for HTTP Echo now has a padlock symbol, which shows that it uses SSL.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Setting a Pass Phrase

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To enable the HTTPS listener to run, you need to enter the pass phrase that you defined for the private key file. In other situations, you might also have a pass phrase for the server certificate, which you would also need to enter. This tutorial does not require one.

There are two ways of setting the pass phrases. One way is to store the pass phrases in a file, and the other is to enter them once the enterprise server is started.

To set the pass phrase in a file:

  1. Edit the file mf-server.dat, located in $COBDIR/etc . If the file does not exist, create it.
  2. Add the following lines to mf-server.dat:
    [HTTPS Echo/SSL/passphrases]
certificate=
keyfile=open sesame

    It does not matter where in the file you add this section. If you like, you can add a comment (preceded by a ";") to describe the entry. Make sure the name HTTPS Echo is spelled exactly as it is in ES Admin.

  3. Start ESDEMO from the home page of ES Admin.
  4. When ESDEMO has started, look at the Listeners page to make sure that the new listener HTTPS Echo has started, as with the other listeners.

To set the pass phrase manually without using a file:

  1. Start ESDEMO from the home page of ES Admin.
  2. When ESDEMO has started, go to the Listeners page. If you didn't enter the pass phrase in the above file, the status of the listener HTTPS Echo is Start pending.
  3. Click Authorize in the Status column of HTTPS Echo. This displays the SSL Listeners page in a separate browser window.
  4. Enter open sesame in the Keyfile Passphrase field, then click Set passphrases. You can leave the Certificate Passphrase field blank, since you did not define a certificate passphrase.
  5. Confirm that the HTTPS Echo is now started by viewing the main Listeners page (and clicking Refresh if necessary).

If you ever have problems starting or running an SSL-enabled listener, it can be useful to look at the MFCS log. Click Server > Diagnostics > CS Console.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Interpreting a Security Alert

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this section as a user connecting to the server, you verify that you have connected to the correct Web site, and that it is trustworthy.

Since the Web site was certified by your Demo CA, you need your Demo CA's self-signed certificate installed in your browser in order for the Web site's certificate to be accepted. The necessary demo CA's self-signed certificate is not installed, so that you can see the messages that this causes.

  1. In your browser, enter https://localhost:9443.

    This uses the secure version of HTTPEcho that you created in the stage Creating a Secure HTTPS Listener.

    You could enter your machine's actual DNS host name or even its dotted decimal IP address rather than localhost. Normally, it should make no difference, but for the purposes of this tutorial, use localhost.

  2. A Security Alert is displayed. It warns you that the Web site's security certificate may not be trustworthy, and it lists what is right and what is wrong with it.

    If this tutorial has already been run and the CA certificate is still installed, you do not get this alert. You can remove the certificate and then restart this section to display the alert.

  3. Close the security alert.

This security alert indicates that you have not installed the self-signed certificate of the CA that issued this server certificate.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Importing the CA's Root Certificate
Verifying the Certificate
Tidying Up


Importing the CA's Root Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Browsers typically come with certificates for well-known CAs already installed, and you rarely need to install them. If you need a CA's root certificate, you can usually download it from the CA's Web site.

The demonstration CA's certificate is not pre-installed in your browser, so you need to install it. It is supplied in the private directory of the demoCA. You install this certificate as follows:

  1. In your browser, go to the options where you manage certificates.
    • In Internet Explorer, click Tools > Internet Options > Content > Certificates. Go to the Trusted Root Certification Authorities tab and click Import.
    • In Mozilla Firefox, click Tools > Options > Advanced. Then scroll down and click Manage Certificates. Click Authorities and then click Import.
  2. Install the CA's self-signed certificate, which is in the private folder of your DemoCA directory. Specify the file CARootCert.cer. Internet Explorer requires X509 certificates, in DER format, so only those are listed, and not the PEM format files. Mozilla Firefox can handle several types, so several are listed and you need to install the PEM-format certificate.
  3. In Internet Explorer, use the Browse button to enter Trusted Root Certification Authorities in the Certificate Store field.

    In Mozilla Firefox, check Trust this CA to identify Web sites.

  4. Look down the list under Trusted Root Certification Authorities (for IE) and Authorities (for Firefox). You will see that your Demo CA is now listed; look for its Common Name. If when you installed Micro Focus Demo CA you chose to use your computer DNS name as the DemoCA's Common Name, it will appear different to the rest, because real CAs tend to give themselves user-friendly Common Names.
Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Verifying the Certificate
Tidying Up


Verifying the Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Now that the CA's certificate is installed, you should be able to connect from the client Web browser.

  1. Try to connect again. In the Web browser, enter https://localhost.
  2. Read the Security Alert again. This time it shows only one problem, which is that the name in the certificate doesn't match the URL you tried to connect to. This is a warning that the certificate might not have come from the desired Web site, but from another Web site masquerading as it.
  3. Click View Certificate. The Issued To name in the certificate is the DNS host name of your computer, and you were trying to connect to localhost, and this is the cause of the discrepancy.
  4. Since this is in fact the desired Web site, click Close > OK.

    The connection is made, and HTTPS Echo sends a page with identification details to your browser, confirming that the connection has been made successfully. It is normal for most of the strings to be empty, as shown.

Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Tidying Up


Tidying Up

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You should remove your Demo CA's self-signed certificate from your Web browser, both to avoid confusion in real use of your browser, and to enable this tutorial to be run again if required.

  1. In your browser, go to the options where you manage certificates.
    • Internet Explorer, click Tools > Internet Options > Content > Certificates. Then go to the Trusted Root Certification Authorities tab.
    • In Mozilla Firefox, click Tools > Options > Advanced. Then scroll down and click Manage Certificates and click Authorities.
  2. Select your Demo CA's certificate (the Common Name, not the organization name), then remove it.
  3. Close the browser and re-open it.
Parent topic: Tutorial: Configuring SSL Security in the Server
Related information
Introduction
Creating a Secure HTTPS Listener
Installing the Server Certificate
Setting a Pass Phrase
Interpreting a Security Alert
Importing the CA's Root Certificate
Verifying the Certificate


Information on OpenSSL

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The openssl.exe utility is installed by default in the directory: /opt/microfocus/DemoCA/openssl or $COBSSL (if set). This directory is pointed to by the SSLDIR environment variable, which is created when you install this pack. The directory is not automatically added to your path, but you might find it useful to add it.

The openssl utility supplied with this pack is a full implementation of the utility, except that certain algorithms that are subject to patents or other legal restrictions have been excluded. See Supported Algorithms in the Readme for a list of the supported algorithms.

You can run openssl from the command line.

For details of the OpenSSL utility, see www.openssl.org and www.mkssoftware.com.

  • OpenSSL Utility
  • OpenSSL Configuration File
  • Algorithms
  • Interpreting OpenSSL Error Messages
  • Supported SSL Versions and Supported Algorithms
Parent topic: Securing Communications


OpenSSL Utility

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The OpenSSL utility is installed by default in /opt/microfocus/DemoCA/openssl or $COBSSL (if set).

The OpenSSL utility supplied with this pack is a full implementation of the utility, except that certain algorithms that we believe to be subject to patents or other legal restrictions have been excluded.

To start the OpenSSL utility, run openssl from the command line.

Parent topic: Information on OpenSSL
Related information
Supported SSL Versions and Supported Algorithms
www.openssl.org
www.mkssoftware.com
OpenSSL Configuration File
Some Common Algorithms
Definitions for OpenSSL


OpenSSL Configuration File

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The OpenSSL configuration file provides SSL defaults for items such as:

  • The location of your certificate files.
  • Your Distinguished Name. This comprises the details of your site (your Common Name, your locality and so on). Initially your Distinguished Name comprises the details you entered during installation.
  • Defaults for the openssl ca policy command, which specifies which elements of the Distinguished Name are required.

The configuration file is called openssl.cnf by default and belongs in the same directory as openssl.exe by default. You can specify a different configuration file by using the OPENSSL_CONF environment variable or you can specify alternative configurations within one configuration file.

The configuration file is a text file and comprises several sections, such as:

  • The ca section, which configures the CA. You can have several ca sections, each specifying a different configuration for a different CA, and switch between them by changing the default_ca option. You can also override this choice from the command line, using the -name parameter. This is useful in development and testing, enabling you to try out different configurations.
  • The policy section, which specifies how closely the Distinguished Name in a certificate presented to SSL software must agree with the Distinguished Name in an installed certificate, for the two certificates to be considered to match.
  • The req section, which configures the openssl req command.
  • The distinguished_name section, which specifies the Distinguished Name fields required when the openssl req command is creating a certificate request or a self-signed certificate. The actual name of this section is specified in the distinguished_name entry in the req section. This enables you to switch between different distinguished_name configurations, by changing the entry in the req section.
  • The attributes, which has attributes such as challengePassword or unstructuredName. Like the distinguished_name section, the actual name of the attributes section is specified in the req section, so that you can have several attributes sections, and switch between them.

In the options in the configuration file, all filenames must be given complete with absolute path.

For full details see OpenSSL CA function on the MKS Software site and page down to the section on the Configuration File .

Parent topic: Information on OpenSSL
Related information
OpenSSL CA function


Algorithms

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You can list the available algorithms using the openssl ciphers and openssl speed functions as follows. Note that not all the algorithms listed are supported. See below.

openssl ciphers

The openssl ciphers function lists the full cipher and hash suite available in the supplied openssl utility. Most of the ciphers available in OpenSSL are supported by Micro Focus Security Pack, but not all of them.

The openssl ciphers function produces output like this:

DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:AES256-SHA:...

Where:

  1. The first element is the method
  2. The next one or more elements (except the last) are the ciphers and might indicate the symmetric and asymmetric ciphers
  3. The last element is the hashing algorithm used for signing

openssl speed

The openssl speed function lists the algorithms supported by the Micro Focus Security Pack and available in the supplied openssl utility. The speed function also lists how long each algorithm takes on your computer. This function takes some minutes to run.

Parent topic: Information on OpenSSL
Related information
Supported SSL Versions and Supported Algorithms
OpenSSL Utility
Some Common Algorithms


Interpreting OpenSSL Error Messages

Restriction: This topic applies only when the Enterprise Server feature is enabled.

OpenSSL produces many error messages which are cryptic at times. This topic does not explain all the OpenSSL error messages, but it gives some guidance on how to interpret the messages.

Here is a typical OpenSSL error message that is caused by faling to set the SSLDIR environment variable to a directory containing openssl.cnf:

C:\Program Files\Micro Focus\DemoCA>openssl ca -revoke srvsert3.p12
Using configuration from /usr/local/ssl/openssl.cnf
error loading the config file '/usr/local/ssl/openssl.cnf'
3792:error:02001003:system library:fopen:No such process:.\crypto\bio\bss_file.c
:104:fopen('/usr/local/ssl/openssl.cnf','rb')
3792:error:2006D080:BIO routines:BIO_new_file:no such file:.\crypto\bio\bss_file
.c:107:
3792:error:0E064072:configuration file routines:CONF_load:no such file:.\crypto\
conf\conf_def.c:197:

The structure breaks down as follows:

  • Command line and parameters
  • Confirmation of configuration file to be used
  • Initial indication of error status
  • Low level code layer error information
  • Medium level code layer error information
  • Top level code layer error information

Within each code layer specific location information is given about what status was generated, within which source module and guidance as to the parameter that caused the error.

The important information is usually found in the final line. In this case the text “no such file” indicates the symptom of the failure. The file might no exist, but we might be looking in the wrong place and need to adjust the SSLDIR accordingly.

The OpenSSL Web site www.openssl.org has several relevant sections, in particular the HOW TO sections.

openssl dsa -in srvkey.pem -out keyout.pem
read DSA key
Enter PEM pass phrase:
unable to load Key
2588:error:06078081:digital envelope routines:EVP_PKEY_get1_DSA:expecting a dsa
key:.\crypto\evp\p_lib.c:241:
Parent topic: Information on OpenSSL
Related information
www.openssl.org
OpenSSL Configuration File


Supported SSL Versions and Supported Algorithms

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Micro Focus Demo CA supports the following versions of SSL, in both client and server mode:

  • SSL V2.0
  • SSL V3.0
  • TLS V1.1

The following algorithms are supported:

  • AES-128 / 192 / 256
  • Blowfish CBC
  • CAST CBC
  • DES CBC / DES EDE3
  • DSA
  • HMAC(MD5)
  • MD2 / MDC2 / MD4 / MD5
  • SHA1
  • RMD160
  • RC2-CBC / RC4
  • RSA
Parent topic: Information on OpenSSL


SSL and PKI Technology Primer

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If you are new to securing communications, it is important that you understand the concepts of how communications are secured.

  • SSL
    This section gives an overview of the whole subject of SSL encryption.
  • CAs and PKIs
    This section describes CAs and PKIs.
  • Checking, Exporting and Importing Certificates Overview
    This tutorial talks through the certificates already installed on your machine, regardless of the Micro Focus Security Pack.
  • Certificates
    This chapter provides some background to certificates.
  • Standards and Organizations
    A great many standards have been created covering SSL and PKI, and as is often the way with new areas some of these standards are rivals or at least alternatives. This chapter briefly introduces the standards referred to in the coming chapters, and the organizations behind these standards.
  • Some Common Algorithms: Overview
    This topic names some of the best known encryption algorithms, and describes how to choose what algorithm to use.
  • Definitions for OpenSSL
    This topic briefly explains some terms that, while they are not part of SSL, often appear in discussions and documentation of SSL, especially of OpenSSL.
  • Attacks
    This topic explains some of the best known strategies for breaking a code, and what features SSL has that you can use to protect yourself from these attacks.
  • Designing a PKI
    This chapter advises on points to remember, ideas to consider, and pitfalls to avoid if you are designing a PKI for your organization. This is by no means an exhaustive list, but is intended to be helpful in suggesting points to consider.
Parent topic: Securing Communications


SSL

This section gives an overview of the whole subject of SSL encryption.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

For most of this section we'll assume, for simplicity, that you are the sender of messages and someone else is the recipient. In practice, of course, you're likely to be sending messages to each other, and so everything we describe is actually happening in both directions.

Throughout this explanation, we have taken care to say "your SSL software does so-and-so" not "you do so-and-so". This is partly to emphasize that all the detailed work is done by the software - as a user, or even as a programmer, of SSL-enabled software you generally just set options. It is also to emphasize that you must keep your computer secure, with such things as login passwords. If someone else can use your SSL software in your place, obviously all security is lost.

  • What is SSL?
  • SSL and TLS Terminology
  • Encryption and Decryption
  • Hashing
  • Signing
  • Certificates
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: What is SSL?


What is SSL?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

SSL is a standard mechanism for sending and receiving electronic communications in encrypted form. SSL can be used wherever confidential information is to be sent between machines, such as a network, a company intranet, or the Internet. For brevity, this book generally talks about the Internet.

SSL is heavily reliant on the use of Public Key Infrastructures (PKIs). A PKI is a system of issuing online certificates to people and organizations involved in electronic communications - such as Web sites - to confirm their authenticity and trustworthiness.

SSL is widely used by organizations large and small. For example, if you use online banking, you may notice that the Web addresses - also known as universal resource locators (URL) - of many pages on your bank's Web site have addresses beginning https rather than http. This indicates that messages between that Web page and the Web site are sent via a version of HTTP that uses SSL.

Any two software programs that communicate with one another and have SSL support can send their messages to one another in encrypted form, provided that they also have a trust relationship with a PKI.

SSL can provide the following benefits:

  • Confidentiality – keeping information private
  • Integrity – ensuring information has not been tampered with
  • Authentication – confirming the identity of the individual who sent the information
  • Non-repudiation – proving that the individual who sent the information did so

Some of the above benefits are provided by PKIs that are used by SSL.

Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: SSL
Next topic: SSL and TLS Terminology


SSL and TLS Terminology

Restriction: This topic applies only when the Enterprise Server feature is enabled.

SSL was originally defined by Netscape. The first publicly released version, SSL v2, came out in 1994. Several vendor-specific variants appeared, notably Private Communications Technology (PCT) from Microsoft. PCT was effectively a rival to SSL v3 when that came out in 1995. The Internet Engineering Task Force (IETF) took on the task of creating an industry-wide standard, and developed what was effectively SSL v3.1. However, they adopted for this the vendor-neutral name of Transport Layer Security (TLS). The terms TLS and SSL are sometimes used interchangeably. In this book we generally keep to the term SSL.

Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: What is SSL?
Next topic: Encryption and Decryption


Encryption and Decryption

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When software with SSL enabled sends a message, it sends it encrypted - that is, in a secret code. The software that receives the message, provided it too has SSL enabled and knows the secret code used, decrypts it - turns it back into the original uncoded message.

This gives you the first of the benefits of SSL mentioned above: confidentiality. If some unintended recipient - known as an eavesdropper, or attacker - picks up the message, they can't decipher it, because they don't know the code.

To encrypt a message, you need a key and an algorithm. A key is a number, and an algorithm is a method of combining this number with your message to create the encrypted message. To take a simple example, imagine you encrypt a message by replacing each letter by the letter two places farther along the alphabet, so that, for example, IBM becomes KDO. Here, "replace each letter by the letter n places farther along the alphabet" is your algorithm, and 2 is your key.

If you were to use a different key, you'd get a completely different code, although you're still using the same algorithm. So if for example n = 1, IBM becomes JCN.

  • Keys and Algorithms
  • Public Keys, Private Keys, and Secret Keys
  • Using Asymmetric and Symmetric Algorithms Together
Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: SSL and TLS Terminology
Next topic: Keys and Algorithms


Keys and Algorithms

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Now it seems obvious that the intended recipient of your coded message needs to know the algorithm and the key, so as to decode the message; and equally it seems obvious that the algorithm and key must be kept secret from everyone else. And so you get the problem of how to let your intended recipient know them - after all, anyone who might be eavesdropping on your messages might be also eavesdropping when you send the algorithm and key.

Luckily, it's not as simple as that.

The algorithms typically used by SSL are so complex (typically taking several pages of mathematics to describe), and the keys used are typically so long (sometimes hundreds of digits long, when written in hex or decimal), that even if someone does know the algorithm, the chances of them guessing the key, or finding it by trial and error, are virtually nil. So, far from keeping algorithms secret, SSL uses well-known algorithms, which have been developed and published over the years by experts in cryptography.

When you are configuring software that uses SSL, it will generally ask you which of these well-known algorithms you want to use. Since the software does all the encryption/decryption for you, you don't need to understand these algorithms (you'd need considerable mathematical knowledge to do so), but you do need to know the names of the best-known ones and a little about their relative advantages and disadvantages. We'll cover this later. We'll mention some well-known ones as we go along.

You don't need to decide a key yourself, either. Instead, your SSL software uses a random number generator to create one.

Parent topic: Encryption and Decryption
Parent topic: SSL and PKI Technology Primer
Previous topic: Encryption and Decryption
Next topic: Public Keys, Private Keys, and Secret Keys


Public Keys, Private Keys, and Secret Keys

Restriction: This topic applies only when the Enterprise Server feature is enabled.

As for keeping the key secret from all but your intended recipient, well, some of the well-known algorithms need two keys - and a message encrypted with one of the keys can only be decrypted with the other. So once you and your intended recipient have agreed which algorithm to use, your recipient's software generates a pair of keys, and sends you one (called his/her public key) while keeping the other one secret, even from you (this one is called his/her private key). Your software then encrypts and sends your message using the public key, and the recipient's software decrypts it using the private key.

So there's no danger of the private key being discovered by an eavesdropper - it never gets sent anywhere. It is known only to its owner.

As for the public key, there's no need to keep it secret. On the contrary, it can safely be made available to anyone who requests it. We'll come back later to how this is done.

An algorithm like this, using a private key and a public key, is called asymmetric. An algorithm that uses just one key, which has to be a secret between the sender and recipient, is called symmetric, and the key is called a secret key.

An algorithm that uses a private key and a public key is also called a public key algorithm. One of the best known ones is RSA, developed by Ron Rivest, Adi Shamir, and Leonard Adleman in 1977. An algorithm that uses just one key, a secret key, is called a secret key algorithm. One of the best known ones is Data Encryption Standard (DES), published as a US standard in 1977.

Parent topic: Encryption and Decryption
Parent topic: SSL and PKI Technology Primer
Previous topic: Keys and Algorithms
Next topic: Using Asymmetric and Symmetric Algorithms Together


Using Asymmetric and Symmetric Algorithms Together

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An asymmetric system has one major disadvantage - the algorithms are very complex and therefore very time-consuming. No matter how fast your computer is, you wouldn't want to use them to encrypt/decrypt large amounts of data.

So encryption software normally uses a symmetric algorithm on the data itself, meaning the secret key has to be sent to the recipient - but in case an eavesdropper intercepts the secret key, the software sends the secret key encrypted, using an asymmetric algorithm.

In this kind of system, the secret key is called a session key, since it is generated when the would-be sender and recipient first connect, sent using the asymmetric algorithm, and then used for all the data transmissions until the session is complete and the connection broken. A new secret key is generated for every new session.

Parent topic: Encryption and Decryption
Parent topic: SSL and PKI Technology Primer
Previous topic: Public Keys, Private Keys, and Secret Keys
Next topic: Hashing


Hashing

Restriction: This topic applies only when the Enterprise Server feature is enabled.

As explained in the chapter SSL, a hash is created by applying an algorithm that combines the characters of a message in some way to produce a string that is meaningless but nevertheless can be regarded as characteristic of the message - the chances of any other message, subjected to the same algorithm, giving the same hash are tiny.

It is neither necessary nor desirable that the hash should be unique; the algorithm should be such that the hash does not contain enough information to reconstruct the original message. So there actually will be other messages (though a tiny subset of the set of all possible messages) that would give the same hash. This important property of a good hashing algorithm is called irreversibility. Nevertheless, it should be difficult to deliberately create two messages that produce the same hash. This property is called collision-resistance.

Just as with encryption, there are various well-known algorithms used for hashing, and your SSL software may let you choose which it uses.

  • MD5
  • SHA
Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Using Asymmetric and Symmetric Algorithms Together
Next topic: Signing
Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: RSA
Next topic: MD5
Related information
RFC2828


Signing

Restriction: This topic applies only when the Enterprise Server feature is enabled.

But imagine the following:

  1. You send a message, encrypted and accompanied by a hash.
  2. An hacker intercepts it and prevents it reaching your intended recipient.
  3. The hacker, pretending to be you, sends a new message, encrypted and accompanied by a hash.
  4. The recipient decrypts this, and finds the hash matches the hash he or she calculates, so believes he or she has received an uncorrupted message from you.

This is called a man-in-the-middle attack.

The solution to this is for your software to send the hash encrypted as well - but encrypted using your own private key. Since you have published your public key, the recipient's software will be able to decrypt the hash and use it. And the recipient can be sure it came from you, since only your software knows the private key that matches your public key.

A hash encrypted with your private key is called a digital signature.

So if you send a message signed in this way, the recipient knows it came from you. This is the third of the benefits of SSL mentioned above: authentication.

In fact, with a digital signature, your recipient can prove it came from you. If you should ever want to deny it, you can't. This is the fourth benefit mentioned above: non-repudiation. In some parts of the world, a digital signature has legal force, like a traditional hand-written signature.

Notice though that, unlike a hand-written signature, a digital signature is different every time - it is an encryption of the hash of the message it is attached to.

A similar idea to this is a message authentication code (MAC), which is a hash encrypted with the secret key of a symmetric algorithm. MACs are used instead of digital signatures to provide integrity, authentication, and non-repudiation in some systems.

Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Hashing
Next topic: Certificates


Certificates

Restriction: This topic applies only when the Enterprise Server feature is enabled.

When asymmetric algorithms were first invented, it was suggested that people should publish their public keys in books like phone books. That idea didn't catch on. Instead, a new standard file type was invented, called a certificate.

A certificate contains its owner's public key and everyday elements of their identity such as their name, company, location, and the DNS host name of their computer. Your SSL software normally includes a function to create your certificate, but it's more usual to get an independent body, called a Certificate Authority, to create it. We'll go into this in the next chapter.

Anyone can have a certificate, and anyone needing to prove their identity online needs one. Notably, they are needed by organizations such as online banks and other Web sites that need clients or other organizations to communicate with them securely.

When you connect to such a Web site, the initial contact (called the handshake) between your SSL software and theirs includes their SSL software sending yours their certificate. This is how you get their public key, so that encrypted communication between you can begin, as described above.

Parent topic: SSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Signing


CAs and PKIs

This section describes CAs and PKIs.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Two of the many well-known CAs on the Internet are VeriSign (http://www.verisign.com) and Thawte (http://www.thawte.com). You may find it useful to look at their Web sites from time to time while reading this chapter.

At this point we need to introduce the term "entity". A user of a network or intranet or the Internet might not be an individual person - it could be an organization, or even a machine. So we'll use the more general term "entity" from now on.

  • Trust
  • What is a CA?
  • What is a PKI?
  • Root and Subordinate CAs
  • How Do you Check a Certificate?
  • Certificate Validity Period and Revocation
  • Types of Certificates - Purpose
  • Authentication Modes
  • Typical Process
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Trust
Related information
Verisign
Thawte


Trust

Restriction: This topic applies only when the Enterprise Server feature is enabled.

So far, we've assumed that you and the people you communicate with know and trust each other. In real life, this is unlikely to be the case. On the Internet, or a big organization's intranet, you are one of a great many people, all potentially communicating with each other, and unlikely ever to know each other personally.

In the previous chapter, we introduced certificates as a way of making an entity's public key available to anyone who wants it.

To prove that the entity is trustworthy, an entity's certificate is created and digitally signed by someone who knows the entity personally, or at least is able to check up on them personally, and who is in turn trusted by others. In this way the certificate also serves - like a traditional paper certificate - as a proof of the entity's trustworthiness. SSL software includes a function to display a certificate on the screen so a user can check the details of the owner and the signatory.

And the person who signed the certificate can in turn have a certificate signed by a third person, and that person can in turn have a certificate signed by a fourth, and so on. Each certificate includes a record of this chain of certificates.

This is called a "web-of-trust model", and in a small organization it may be sufficient, since it's fairly easy to ensure that anyone checking a certificate will find someone he or she knows and trusts in the chain of signatories on the certificate. But it's not scalable; that is, it won't work for a big organization consisting of thousands of people mostly unknown to each other - and certainly not for the Internet.

The solution to this is a PKI, which we describe later in this chapter.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: CAs and PKIs
Next topic: What is a CA?


What is a CA?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Since you yourself can't possibly check up on all your contacts, you need someone who can - someone who can investigate entities, perhaps meet them in person, and then provide a statement to other entities that they are trustworthy. A Certification Authority (CA) is a body that does this. For an intranet, the CA might be a department within your organization. For the Internet, there are well-known CAs that provide this service.

  • How does the CA show it trusts an entity?
  • How does the CA check on entities?
  • Why should you trust the CA?
  • How do you know the certificate really came from the CA?
Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Trust
Next topic: How does the CA show it trusts an entity?


How does the CA show it trusts an entity?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

They issue certificates. Once they have satisfied themselves that an entity is genuine and trustworthy, they create a certificate as described above, containing the entity's public key, and the entity's identity details such as name, location, DNS host name, etc. They send this certificate to the entity to store, and keep a copy themselves.

The CA generally has a server dedicated to this function, and this machine is also known as the CA.

You can configure your SSL software to compare a received certificate to a list of known trusted CAs. As described above, you can also have your SSL software display a certificate on your screen for you to check the details.

Parent topic: What is a CA?
Parent topic: SSL and PKI Technology Primer
Previous topic: What is a CA?
Next topic: How does the CA check on entities?


How does the CA check on entities?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This is an important point, and a CA will have a Certificate Policy (or Practice) Statement (CPS) explaining how they do it. Typically this is available on the CA's Web site for anyone to read.

This check is what anchors electronic communications to the real world. Typically it involves the entity, or its representatives if it is an organization, actually presenting themselves in person to the CA, with proof of identity. If this is not practicable because entities wanting certification are geographically wide-spread, the CA will have Registration Authorities, local branches that carry out the in-person checks and then forward approval to the central CA.

Again, the RA uses a server which is itself known as the RA. The connection between the RA and CA is likely to be an electronic one - the RA notifies its approval to the CA, which then issues the certificate. At both levels, though, there are likely to be actual human beings making the decisions to recognize the proofs of identity, and to grant the certificates.

If the entities wanting certification are too widespread even for RAs to be within reach of them all, then the CA may use notaries - individuals authorized to check identification in person and forward the details to the CA or one of its RAs.

All these policies should be detailed in the CA's CPS - this document and the policies it describes are as important a part of a PKI as the SSL technology itself.

Parent topic: What is a CA?
Parent topic: SSL and PKI Technology Primer
Previous topic: How does the CA show it trusts an entity?
Next topic: Why should you trust the CA?


Why should you trust the CA?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The above all depends on the CA themselves being trustworthy. Who gave them the right to check identities and issue certificates pronouncing people trustworthy?

For the intranet of a company or other organization, the CA is likely to be a department set up at the management's direction. For the Internet, a number of privately run CAs have been established, which have become widely trusted simply because they have earned a world-wide reputation.

To maintain its reputation, a CA would be expected to keep its CA server extremely secure, not only from hackers, but also from physical on-site interference, to ensure that certificates cannot be created other than by the official route. If you read a CA's CPS, you should expect to find strict, detailed rules about physical access to the server by the CA's staff.

Parent topic: What is a CA?
Parent topic: SSL and PKI Technology Primer
Previous topic: How does the CA check on entities?
Next topic: How do you know the certificate really came from the CA?


How do you know the certificate really came from the CA?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

They sign it.

In addition to the data described earlier (the public key, name , etc of the certified entity), a certificate contains the CA's digital signature. As described earlier, this provides proof - in some countries, legal proof - that it came from the CA.

Parent topic: What is a CA?
Parent topic: SSL and PKI Technology Primer
Previous topic: Why should you trust the CA?
Next topic: What is a PKI?


What is a PKI?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A PKI is the whole system described in the preceding sections - one or more CAs, their procedures (defined in their CPS's) for vetting applicants for certificates, and for handling and issuing certificates, and the SSL software used by entities to send, receive, and check certificates.

The Internet has, in effect, its own world-wide PKI, based around internationally known CAs such as Thawte, VeriSign and others. An organization, such as a company, can set up its own PKI for use within its intranet or network.

The same SSL software and world-wide standards (such as certificate formats) would normally be used in either case. The principal distinction between the world-wide PKI and a private one is that in a private one the organization would set up its own CAs, recognized within the organization.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: How do you know the certificate really came from the CA?
Next topic: Root and Subordinate CAs


Root and Subordinate CAs

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If there were only a few CAs in the world, they would soon become overloaded. In fact, there are many. But how does a new CA show its trustworthiness? Usually, by applying for and being granted a certificate from one of the established CAs. A CA certified by another is called a subordinate CA.

A CA that is not certified by any other, but relies solely on its own reputation, is called a root CA. Even a root CA needs a certificate (we'll see below why), and the format of a certificate requires that it be signed, so they create and sign their own certificate. This is called a self-signed certificate or a root certificate.

Similarly, in a large organization, there might be subordinate CAs - for example, each department might run its own CA, each certified by the organization's root CA.

Also, a big CA such as those on the Internet might find that to cope with demand they need several CA machines. Each of these is a subordinate CA, with a certificate granted by one root CA machine.

A subordinate CA can itself certify subordinate CAs, so the standard format for a certificate includes a record of a chain of CAs, each certified by the next, back to a root CA. This chain of certificates is called the certification path. Thus a PKI is hierarchical. You trust the certificate if you know and trust any of the CAs on the certification path.

So in contrast to the web of trust described earlier, a PKI is a tree of trust, with one or more root CAs at the top, subordinate CAs below them and the actual users (client or server) at the bottom.

In a minor departure from this hierarchical nature, CAs can also cross-certify each other. For example, two government departments might each have its own PKI, with its own CA. Within each department, every member has been vetted and then certified by the relevant CA. They might then find that members of the two departments frequently need to communicate with each other. To establish trust between all the members of the two departments, effectively linking the two PKI's into one, all that is needed is for the two CAs to grant each other certificates.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: What is a PKI?
Next topic: How Do you Check a Certificate?


How Do you Check a Certificate?

Restriction: This topic applies only when the Enterprise Server feature is enabled.

We said above that the SSL software compares a certificate to a list of known CAs. We'll describe more precisely what happens.

A CA itself has a certificate - a self-signed one in the case of a root CA. Your SSL software can store certificates (known as installing a certificate), and typically comes with the certificates of a number of well-known CAs already installed. You can install more, if you come across more CAs you wish to trust. Also, there may be periodic updates - for example, the automatic updates that Microsoft send out for Windows XP sometimes install additional CA certificates in Internet Explorer.

When your SSL software receives an entity's certificate as part of a handshake, it compares the hierarchy of CAs named in the certificate to the installed CA certificates. If any in the hierarchy matches any in the installed list, then the entity is considered to have been certified by a known and trusted CA.

Your SSL software also needs to check that the CA's digital signature in the entity's certificate is genuine. Remember that to check a digital signature your SSL software decrypts it using its owner's public key, and then compares the resulting decrypted hash with the hash that the SSL software has itself worked out from the message (in this case the entity's certificate). The SSL software obtains the CA's public key from the CA's certificate.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Root and Subordinate CAs
Next topic: Certificate Validity Period and Revocation


Certificate Validity Period and Revocation

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Optionally, a certificate can contain start and end dates, when it starts and ceases to be valid. End dates are especially common, since most CAs consider it good policy to require a certificate to be renewed from time to time. Not only does it enable them to check that the holder is still genuine, but it enables them to charge for renewing the certificate.

It is sometimes necessary for a CA to revoke a certificate, for example if the holder's matching private key is lost or revealed, or if the CA ceases to consider the holder trustworthy. There are two ways a CA can do this. Both have shortcomings.

The first is to maintain a certificate revocation list (CRL), which it makes remotely accessible. A CRL can be installed in SSL software, for example in a browser, and when the SSL software is examining a certificate to see if it is trustworthy, part of the procedure is to see if the certificate is on any of the installed CRLs.

This approach has the problem that CA updates are issued periodically, so there is a delay between a CA deciding to revoke a certificate and the fact appearing in the latest issue of the CRL.

A more recent solution is for the CA to provide online certificate status - meaning that SSL software checking a certificate can contact the CA's server online and get a signed response saying whether the certificate has been revoked. The Online Certificate Status Protocol (OCSP) has been introduced for this.

This approach has the problem that it puts a high load on the CA's server.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: How Do you Check a Certificate?
Next topic: Types of Certificates - Purpose


Types of Certificates - Purpose

Restriction: This topic applies only when the Enterprise Server feature is enabled.

CAs issue different kinds of certificates, differing in what kind of checks the CA has made on the owner and consequently what purpose the certificate serves - in what roles it guarantees the owner as trustworthy. For example:

  • Typically, a CA issues its own root CA machine with a self-signed root certificate
  • If you are the owner of a Web site accessed by the general public, you can request a server identification certificate (server certificate for short), confirming to your clients the identity of your server
  • If you are engaged in business-to-business communications (B2B), you will probably want a client certificate, confirming the identity of your site

Exactly what the certificate certifies - in other words, its purpose - is stated in the certificate.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Certificate Validity Period and Revocation
Next topic: Authentication Modes


Authentication Modes

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In a client/server scenario, it may be that only the server has a certificate, so that the clients can confirm the identity of the server; or it may be that clients too are required to have certificates, so that the server can identify their identities.

If only the server has a certificate, the online service is said to be operating in server-only authentication mode. If the clients too have certificates, the service is operating in full authentication mode.

If as a Web site owner you want the benefits of non-repudiation, that is, you want to be able to prove that data really was sent to you from a particular client, then you should use full authentication.

Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Types of Certificates - Purpose
Next topic: Typical Process


Typical Process

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Here's a brief, simplified overview of what typically happens when you contact a secure Web site, that is, one using SSL. Let's say you are a Web user contacting your online bank.

In the following, remember that a symmetric algorithm is normally used to encrypt the data itself, while an asymmetric algorithm is used only to send the secret key for the symmetric algorithm.

In the following, we refer to "your browser" and "the bank's server". Of course we mean the SSL software in each.

  1. You enter the URL of the bank's login page.
  2. Your browser sends a list of symmetric algorithms it can support to the bank's server, and requests the bank's certificate.
  3. Their server replies saying which symmetric algorithm to use, and sends the requested certificate. It also sends a random number to be used in generating the secret key.
  4. Your browser checks the hierarchy of CAs shown in the bank's certificate against the CA certificates you've got installed. If there is no match, the browser flags a warning.
  5. If there is any match, the browser checks the bank's certificate against the CA that issued it, typically making the following checks and flagging a warning if any fail:
    • Checks the CA's digital signature in the bank's certificate.

      Remember this signature is the encrypted hash of the bank's certificate - encrypted using the CA's private key. Your browser gets the CA's public key from the CA's certificate, and uses it to decrypt the signature, thus getting back the hash. Your browser then itself hashes the bank's certificate, and checks the two hashes match.

    • Checks the start and expiry dates in the certificate to confirm the certificate is current.
    • Checks the URL in the certificate is exactly the same as the URL DNS name of the machine that sent the Web page.
    • Checks in the CA's certificate revocation list (CRL), or contacts the CA's server using OCSP, to see if the certificate has been revoked.
  6. Your browser generates a random number, encrypts it with the asymmetric algorithm using the bank's public key, and sends it to the bank's server.
  7. The bank's server uses the bank's private key to decrypt the random number the browser sent.
  8. Your browser and the bank's server now independently calculate the secret key from the two random numbers.
  9. As a final check, your browser and the bank's server send each other MACs of all the above messages, and check them to ensure no attacker has altered any of the messages.
  10. Your browser and the bank's server can now send each other your data confidentially, using the chosen symmetric algorithm.
Parent topic: CAs and PKIs
Parent topic: SSL and PKI Technology Primer
Previous topic: Authentication Modes


Checking, Exporting and Importing Certificates Overview

This tutorial talks through the certificates already installed on your machine, regardless of the Micro Focus Security Pack.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Viewing Certificates
  • Checking a Certificate
  • Exporting a Certificate from Internet Explorer
  • Importing a Certificate into Mozilla Firefox
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Viewing Certificates


Viewing Certificates

Restriction: This topic applies only when the Enterprise Server feature is enabled.

There are probably some certificates already installed on your machine. Applications that use SSL, such as a Web browser, usually come with certificates for well-known Web sites and CAs. New certificates for Web sites with newly established reputations are often included in the regular updates that are published for the applications.

  • With Internet Explorer
  • With Mozilla Firefox
Parent topic: Checking, Exporting and Importing Certificates Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Checking, Exporting and Importing Certificates Overview
Next topic: With Internet Explorer


With Internet Explorer

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your browser is Internet Explorer:

  1. Click Tools > Internet Options > Content.
  2. Click Certificates and then the Trusted Root Certification Authorities tab on the far right.

    This lists the root CAs known and trusted by your Web browser - that is, the CAs whose certificates have been installed in the SSL software in your Web browser. A default set of these, consisting of many of the world's best known ones, is installed when Internet Explorer is installed.

    The terminology used in Internet Explorer is slightly different from that used in this book, as follows:

    Internet Explorer | This book
    Personal certificate | Your client certificate
    Other people's | Client or server certificate of some other entity
    Intermediate CA | Subordinate CA
    Trusted root CA | Root CA
  3. Double-click any one of the certificates shown. This displays the certificate on the screen. In many cases the "Issued To" and "Issued by" names are the same, indicating a self-signed certificate - one issued by a root CA to itself.
  4. Double-click one of the certificates. This displays the certificate. Notice that the "Issued To" and "Issued by" names are the same. This is what you would expect from a self-signed certificate - one issued by a root CA to itself.
  5. Click the Certification Path tab. This lists the chain of CAs from the certificate back to the root CA. Because this certificate is for a root CA, there is just one entry.
  6. Click OK to close the certificate.
  7. Click the Intermediate Certification Authorities tab. This shows a list of subordinate CAs whose certificates have been installed in your Internet Explorer.
  8. Double-click one of the certificates.
  9. Click Certification Path. You now see the chain of CAs, from the subordinate CA that issued this certificate, back up through the hierarchy to the root CA.
  10. Close the dialog boxes.
Parent topic: Viewing Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: Viewing Certificates
Next topic: With Mozilla Firefox


With Mozilla Firefox

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your browser is Mozilla Firefox:

  1. Click Tools > Options > Advanced. Then, depending on your version, either scroll down and click Manage Certificates, or click the Security tab and then View Certificates.
  2. Click the Authorities tab. This lists the CAs known and trusted by your Web browser - that is, whose certificates have been installed in the SSL software in your Web browser. A default set of these, consisting of many of the world's best known ones, is installed when Firefox is installed.
  3. Double-click any one of the certificates shown. This displays the certificate on the screen. In many cases the "Issued To" and "Issued by" names are the same, indicating a self-signed certificate - one issued by a root CA to itself.
  4. Click the Certification Path tab. This lists the chain of CAs from the certificate back to the root CA. If this certificate is for a root CA, there is just one entry.
  5. Click OK to close the certificate.
  6. Look at some other certificates in the same way. You may find that all the certificates are for root CAs. If you find one for a subordinate CA, you can see the chain of CAs, from the subordinate CA that issued this certificate, back up through the hierarchy to the root CA.
  7. Close the dialog boxes.
Parent topic: Viewing Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: With Internet Explorer
Next topic: Checking a Certificate


Checking a Certificate

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Frauds have sometimes been perpetrated in which fake Web sites masquerade as genuine sites - when you think you are connecting to the genuine site, for example your online bank, you are in fact diverted to a fraudulent one designed to look like it, and trick you into revealing your confidential details. This kind of fraud is called "phishing".

As a safeguard against this, you can view the certificate of the site you are connecting to.

  • With Internet Explorer
  • With Mozilla Firefox
Parent topic: Checking, Exporting and Importing Certificates Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: With Mozilla Firefox
Next topic: With Internet Explorer


With Internet Explorer

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your browser is Internet Explorer:

  1. Go to the Web site for any online entity that needs secure communications, such as an online bank.
  2. Follow the links to the first logon page. You do not need to logon.
  3. Look at the URL. You should find that it begins with https instead of http. HTTPS is Secure HTTP, the version of HTTP that uses SSL.
  4. Look at your Web browser's status line. You should see a symbol like a padlock. This shows that communications on this page use SSL.

    Some pages contain both secure (that is, encrypted) and insecure (unencrypted) information. If you view such a page, your browser might display a warning to this effect, and ask you if you want to continue. If you choose to continue, the padlock symbol disappears, because Internet Explorer does not treat such pages as secure. You will need to try some other HTTPS page to continue with this tutorial.

  5. Double-click the padlock symbol. This displays the entity's certificate.

    Click the Certification Path to show the hierarchy of CAs from the one that issued the certificate up to the root CA.

    A Web site that was masquerading as the one you believe you've contacted could not fake a certificate, because no reputable CA, having checked up on them, would sign a certificate for them. And since the list of CAs in your browser includes only genuine, reputable CAs, there will be no match and your browser will reject their certificate.

    However, even for the most respectable organizations, you will sometimes find warning messages on the General tab saying that in some respects the certificate is faulty. This is because some detail on the certificate is incorrect - for example, the expiry date may have passed. It is up to you to look at the details on the certificate, and decide whether you trust the Web site despite this flaw.

Parent topic: Checking a Certificate
Parent topic: SSL and PKI Technology Primer
Previous topic: Checking a Certificate
Next topic: With Mozilla Firefox


With Mozilla Firefox

Restriction: This topic applies only when the Enterprise Server feature is enabled.

If your browser is Mozilla Firefox:

  1. Go to the Web site for any online entity that needs secure communications, such as an online bank.
  2. Follow the links to the first logon page. You do not need to logon.
  3. Look at the URL. You should find that it begins with https instead of http. HTTPS is Secure HTTP, the version of HTTP that uses SSL.
  4. Look at your Web browser's status line. You should see a symbol like a padlock. This shows that communications on this page use SSL.

    Some pages contain both secure (that is, encrypted) and insecure (unencrypted) information. If you view such a page, your browser should display a warning to this effect, and ask you if you want to continue. If you choose to continue, the padlock symbol appears with a line through it, because Firefox does not treat such pages as secure. You can still view the certificate though.

  5. Double-click the padlock symbol.
  6. On the Page Info dialog box that appears, click View. This displays the entity's certificate. If you click the Details tab, you will see the hierarchy of CAs from the one that issued the certificate up to the root CA.

    A Web site that was masquerading as the one you believe you've contacted could not fake a certificate, because no reputable CA, having checked up on them, would sign a certificate for them. And since the list of CAs in your browser includes only genuine, reputable CAs, there will be no match and your browser will reject their certificate.

    However, even for the most respectable organizations, you will sometimes find warning messages on the General tab saying that in some respects the certificate is faulty. This is because some detail on the certificate is incorrect - for example, the expiry date may have passed. It is up to you to look at the details on the certificate, and decide whether you trust the Web site despite this flaw.

Parent topic: Checking a Certificate
Parent topic: SSL and PKI Technology Primer
Previous topic: With Internet Explorer
Next topic: Exporting a Certificate from Internet Explorer


Exporting a Certificate from Internet Explorer

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To export a certificate from Internet Explorer in the appropriate format, ready for importing into Firefox:

  1. In Internet Explorer click Tools > Internet Options.
  2. Go to the Content tab and double-click Certificates.
  3. Go to the Trusted Root Certificate tab and find the certificates marked Verisign Trust Network. There are several notable features of these certificates:
    1. There are multiple certificates and each one is unique.
    2. These different types of certificates are used to confirm the trust of different types of identification certificates.
    3. Some of these certificates have passed their expiry date. However they are still valid and should be present to prove the trust path for certificates that were signed during their working life span.
    4. Some of these certificates are direct replacements for expired or about-to-expire certificates.
    5. The life of the replacement certificates is typically far longer than that of the original certificates. Replacing certificates is problematic as it involves a significant amount of manual work and therefore distribution that is not often undertaken. To avoid the distribution complication it is in the interest of all identification certificate users to use certificates with a long life.
  4. Select a certificate and click Export.
  5. In Certificate Export Wizard, click Next.
  6. You choose the format required by your target browser. If you don't know the format required, you can generate a few of the most common formats and save them to different files, so that the correct format is available.

    Select DER encoded binary X.509 and click Next.

  7. Specify the /opt/microfocus/DemoCA/openssl/Verisign as the name of the file to export to and click Next.
  8. On the final screen notice:
    • Export Keys is always "No” when handling CA root certificates.
    • Include all certificates in the certification path is always “No” when using file formats that cannot support multiple certificates. When using a server certificate signed by an intermediate CA you would usually export the complete chain of trust back to the fully trusted CARoot. In this case we would have chosen a different format at step 6.
    • File Format should match the filename extension in most cases,. Although there are times when various subformats such as .p7b and .p7c are interchanged to aid portability of the generated output file.
  9. Click Finish > OK and the file appears in the chosen directory.
  10. Close all the open IE dialog boxes.
Parent topic: Checking, Exporting and Importing Certificates Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: With Mozilla Firefox
Next topic: Importing a Certificate into Mozilla Firefox


Importing a Certificate into Mozilla Firefox

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  1. In Firefox, go to Tools > Options.
  2. Go to the Advanced tab and the Security sub-tab and click View Certificates.
  3. Go to the Authorities tab and click Import. Note that different tabs show different files without an extension indicating that they are native format
    • Files with a .p12 extension are shown without the extension when you import from the Your Certificates tab
    • Files with a .cer are shown without the extension when you import from the other certificate type tabs

    This emphasises the value of understanding how the different types of certificate usage affect the type of file being used to transport a certificate. Other certificate stores may have different rules about formats. It is worth investigating they destination locations requirements before attempting to create certificate files for their use.

  4. Specify the file that you exported from Internet Explorer.

    A message should popup telling you that this certificate already exists. This confirms that file was correctly formatted and read by the import tool.

Parent topic: Checking, Exporting and Importing Certificates Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Exporting a Certificate from Internet Explorer


Certificates

This chapter provides some background to certificates.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Certificate and Key Formats
  • Don't Edit Certificates and Key Files
  • To Convert Certificate Formats
  • Multiple PEM Format Certificates
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Certificate and Key Formats


Certificate and Key Formats

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Certificates are often known as X.509 certificates, since X.509 is the standard that defines their context and layout. The commonest algorithms for creating public and private keys are RSA and DSA, and keys are often referred to as RSA keys or DSA keys. None of these, however, define the format of the file in which a certificate or key is held. There are many rival formats for these files. Some of the commonest standard formats are:

  • DER. This format can contain private keys (RSA or DSA), public keys (RSA or DSA) and X.509 certificates. It is headerless. It is the default format for most browsers. A file can contain only one certificate. Optionally the certificate can be encrypted. The standard extension is .cer, but might be .der in some installations.
  • PEM. This format can contain private keys (RSA or DSA), public keys (RSA or DSA) and X.509 certificates. It is the default format for OpenSSL. It stores the data in either ASN.1 or DER format, surrounded by ASCII headers, so is suitable for sending files as text between systems. A file can contain multiple certificates. The standard extension is .pem.
  • PKCS#12. This is also known as PFX. This format can contain private keys (RSA or DSA), public keys (RSA or DSA) and X.509 certificates. It stores them in a binary format. The standard extension is .pfx or .p12.
  • PKCS #7. This is the Cryptographic Message Syntax Standard. A file can contain multiple certificates. Optionally they can be hashed. Optionally a certificate can be accompanied by a private key. As well as the original PKCS #7, there are three revisions: a, b, and c. The standard extensions for these four versions are .spc, .p7a, .p7b and .p7c respectively.
Parent topic: Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: Certificates
Next topic: Don't Edit Certificates and Key Files


Don't Edit Certificates and Key Files

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You must never edit the contents of a certificate or keyfile. If you change anything within a certificate, any SSL software examining the certificate to authenticate your identity will detect it has been tampered with and declare it invalid.

A keyfile, and in certain circumstances a certificate file, will always be protected by its own security pass phrase. This pass phrase prevents certificate and key file management tools from making unauthorized access to the file content.

Parent topic: Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: Certificate and Key Formats
Next topic: To Convert Certificate Formats
Related information
Certificates


To Convert Certificate Formats

Restriction: This topic applies only when the Enterprise Server feature is enabled.

To convert certificate formats, use openssl.exe, as follows:

  • To convert binary-only PKCS7 (.p7 .p7a .p7b .p7c) files as output from Windows Internet Explorer Certificate Manager, with single or multiple certificate content, and generate human readable text content in the output file:
        openssl pkcs7 -inform DER -in filename.p7b -text -print_certs -out outfilename.pem

    For example:

    openssl pkcs7 -inform DER -in IECert.p7b -text -print_certs -out IECert.pem
  • To convert binary-only PKCS7 files as output from Windows Internet Explorer Certificate Manager, with single or multiple certificate content, and generate only binary content in the output file leave out the “-text” element:

openssl pkcs7 -inform DER -in filename.p7b -text -print_certs -out outfilename.pem

    Example:

    openssl pkcs7 -inform DER -in IECert.p7b -text -print_certs -out IECert.pem

    When handling many certificates in one file you might encounter issues of space being taken for the descriptive text content. In these circumstances you may wish to remove the text content, however this is not recommended for normal use as it make handling of the certificates harder because their content is not immediately viewable.

    Some applications do not accept X509v3 certificates when accompanied by a text description within the certificate file. You can overcome this for most applications, by editing the certificate to trim the text sections, but take care to leave intact the lines beginning and terminating the binary certificate data.

  • To convert PEM to PKCS#12 (to install in a Web browser or for storage):
    • If your PEM-format certificate and key are both in one file, use:
      openssl pkcs12 -export -in pem-cert-and-key-file -out pkcs12-cert-and-key-file
    • If they are in separate files, use:
      openssl pkcs12 -export -in pem-cert-file -inkey pem-key-file -out pkcs12-cert-and-key-file

    Both these commands put the certificate and keyfile into one file. If you intend to store your private key and certificate together in this fashion you should apply a pass phrase to the resultant file.

  • To convert PKCS#12 to PEM:

    • openssl pkcs12 -in pkcs-12-cert-and-key-file -out pem-cert-and-key-file
  • To convert ASN.1 PEM files to DER PEM :
    • If the PEM file contains DSA keys, use:
      openssl dsa -inform PEM -outform DER -in pem-file -out der-file
    • If it contains RSA Keys, use:
      openssl rsa -inform PEM -outform DER -in pem-file -out der-file
  • To convert DER (.cer in most implementations) to PEM:
    • If the DER file contains DSA keys, use :
      openssl dsa -inform DER -outform PEM -in der-file -out pem-file
    • If it contains RSA Keys, use:
      openssl rsa -inform DER -outform PEM -in der-file -out pem-file
Parent topic: Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: Don't Edit Certificates and Key Files
Next topic: Multiple PEM Format Certificates


Multiple PEM Format Certificates

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Normally there is only one certificate in a file. OpenSSL generally assumes this is the case, so it ignores any after the first when handling server and client certificates.

However, a file can contain multiple PEM and PKCS7 format certificates. This is useful for storing a bundle of the root certificates of the CAs you trust, or a certificate verification chain. To use the certificates, you will need to split the file into one file per certificate.

You can split the file using a text editor, but you must take care to not change the data for each individual certificate. Each certificate takes the following format and is terminated by the END CERTIFICATE line:

optional-header-info
------BEGIN optional-text CERTIFICATE-----
...
------END optional-text CERTIFICATE-----

As long as you do not change or break up the data within the BEGIN and END lines, the certificate itself is complete. A certificate is rendered useless unless it retains its binary composition that was created when it was originally signed.

Parent topic: Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: To Convert Certificate Formats


Standards and Organizations

A great many standards have been created covering SSL and PKI, and as is often the way with new areas some of these standards are rivals or at least alternatives. This chapter briefly introduces the standards referred to in the coming chapters, and the organizations behind these standards.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • X.509
  • PKCS Standards
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: X.509


X.509

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The most important standard for PKI's is X.509, which defines the format and content of digital certificates and how to validate them. It is an International Telecommunications Union (ITU) Recommendation, published as ITU-T X.509 and ISO/IEC/ITU 9594-8.

Standards are still evolving, and different companies have implemented it in different ways. For example, Netscape and Microsoft both use X.509 certificates in their Web servers and browsers, but an X.509 certificate created by Netscape may not be readable by Microsoft products, and vice versa.

Parent topic: Standards and Organizations
Parent topic: SSL and PKI Technology Primer
Previous topic: Standards and Organizations
Next topic: PKCS Standards


PKCS Standards

Restriction: This topic applies only when the Enterprise Server feature is enabled.

There is a set of de facto cryptographic message standards called Public Key Cryptography Standards (PKCS) which were originally developed and are still maintained by RSA Laboratories. (For more detailed information, see the Web page at RSA Laboratories.

The standards that are most relevant to PKI are:

  • PKCS #7, Cryptographic Message Syntax Standard. A general syntax for data to which cryptography can be applied, such as digital signatures and encryption. It also provides a syntax for disseminating certificates or certificate revocation lists (CRLs).
  • PKCS #10, Certification Request Syntax Standard. Provides a format for a request for a certificate.
  • PKCS #12, Personal Information Exchange Syntax Standard. Primarily provides a format for storing keys or a certificate in a file.
Parent topic: Standards and Organizations
Parent topic: SSL and PKI Technology Primer
Previous topic: X.509
Related information
RSA Laboratories


Some Common Algorithms: Overview

This topic names some of the best known encryption algorithms, and describes how to choose what algorithm to use.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Algorithms and Key Lengths
  • Choosing an Algorithm
  • Symmetric Algorithms
  • Asymmetric Algorithms
  • Hashing
  • Digital Signatures
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Algorithms and Key Lengths


Algorithms and Key Lengths

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Two things that your SSL software may let you choose are the algorithm and the key length to be used for encryption. One thing to consider in choosing is how easy the code will be to crack.

In general, for the same algorithm, the longer the key the harder the code is to break. This is simply because a would-be attacker can easily use a computer to try key after key until hitting on the right one. The longer the key, the longer it takes to generate all possible numbers of that length, looking for the right one. You need a key that is so long that even with the most powerful computers this would take an impracticably long time.

Of course, computers are constantly becoming more powerful. Therefore, the length of key considered necessary is constantly increasing as the years pass. At the time of writing (early 2005), a key length of 128 bits is generally considered adequate for reasonable security using a symmetric algorithm, while with an asymmetric algorithm 2048 bits is considered adequate.

Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Some Common Algorithms: Overview
Next topic: Choosing an Algorithm


Choosing an Algorithm

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In choosing which algorithm to use, there are several factors to consider.

Cryptography, the invention of new algorithms and of ways to break the codes they create, is a branch of mathematics that is constantly advancing. Attempts to crack a particular algorithm are often undertaken by serious researchers anxious to confirm whether the algorithm is really secure.

It may be possible for an expert cryptographer to find a mathematical way of breaking an algorithm, or it may be vulnerable to a "brute force" attack - just trying different keys until the correct one is found.

Just because an algorithm has been cracked in the past does not necessarily mean you must not use it - you should consider whether your data is valuable enough to tempt a hacker to devote the resources that have been shown to be needed to crack it.

Two problems with all symmetric algorithms are that the key has to be known to both sender and receiver, and so it could be intercepted when being sent from one to the other; and that if the same key is used for all your messages, any eavesdropper who finds out the key can decrypt all your messages.

Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Algorithms and Key Lengths
Next topic: Symmetric Algorithms


Symmetric Algorithms

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In this section we briefly describe some of the best-known symmetric (secret key) algorithms.

A symmetric algorithm that treats the message to be encrypted as a continuous stream of bits is called a stream cipher. A symmetric algorithm that splits the message up into chunks and encrypts each chunk is called a block cipher. The only stream cipher to have been widely used is RC4.

  • RC4
  • DES
  • Triple DES
  • AES
  • Blowfish
  • Twofish
Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Choosing an Algorithm
Next topic: RC4


RC4

Restriction: This topic applies only when the Enterprise Server feature is enabled.

RC4 was designed by Ron Rivest of RSA Security in 1987. It stands for "Rivest Cipher 4", or alternatively for "Ron's Code". RC4 is a widely-used cipher. (There are related algorithms RC2, RC5 and RC6.)

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: Symmetric Algorithms
Next topic: DES


DES

Restriction: This topic applies only when the Enterprise Server feature is enabled.

One of the most well-known secret key algorithms is the US Data Encryption Standard (DES). It was published in 1977. In the past the US government encouraged users to adopt this as the main or only secret key algorithm in use. In 1998, it was shown that a dedicated hacker with moderate computer power can crack it (see EFF DES cracker project), but it is often considered secure enough for some trivial uses. It is to be replaced as a US standard by the Advanced Encryption Standard (AES).

DES uses a fixed key length of 64 bits. Of these, 8 are used for parity, so in effect the key is 56 bits long.

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: RC4
Next topic: Triple DES
Related information
EFF DES cracker project


Triple DES

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A variation on DES is simply to encrypt the message three times in succession, using DES. One long key is split into three shorter keys, one for each encryption, so the overall key length is three times that of regular DES. Triple DES is usually written as 3DES. It is considered secure enough for most uses

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: DES
Next topic: AES


AES

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This is US standard FIPS-197, and is designed as a replacement for DES. It uses an algorithm designed by Joan Daemen and Vincent Rijmen (see csrc.nist.gov/CryptoToolkit/aes/rijndael/Rijndael-ammended.pdf, and known as the Rijndael algorithm.

AES is currently considered secure for commercial use.

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: Triple DES
Next topic: Blowfish
Related information
csrc.nist.gov/CryptoToolkit/aes/rijndael/Rijndael-ammended.pdf


Blowfish

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This was developed by Bruce Schneier of Counterpane Labs. It is used in a great many products, and is standard in the OpenBSD operating system. For details see www.counterpane.com/blowfish.html.

Blowfish is currently considered secure for commercial use.

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: AES
Next topic: Twofish
Related information
www.counterpane.com/blowfish.html


Twofish

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This too was developed by Bruce Schneier, and is efficient when implemented in hardware and smart cards. For details see www.counterpane.com/twofish.html.

Twofish is currently considered secure for commercial use.

Parent topic: Symmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: Blowfish
Next topic: Asymmetric Algorithms
Related information
www.counterpane.com/twofish.html


Asymmetric Algorithms

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The two best known asymmetric (public key) algorithms are D-H and RSA.

  • Diffie-Hellman (D-H)
  • RSA
Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Twofish
Next topic: Diffie-Hellman (D-H)


Diffie-Hellman (D-H)

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Whitfield Diffie and Martin Hellman were the first to show, in a paper published in 1976, that a code could be devised that was encoded using one key and decoded using another.

James Ellis wrote a paper in 1970 on similar work done by himself and Clifford Cocks, but it was covered by the UK's Official Secrets Act, and was not published until many years later.

Using the Diffie-Hellman (D-H) algorithm, one key is specifically for encryption and the other for decryption - you can't use them the other way around. This makes it unsuitable for a PKI system as normally used.

Parent topic: Asymmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: Asymmetric Algorithms
Next topic: RSA


RSA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

It was Ron Rivest, Adi Shamir, and Leonard Adleman who later developed an algorithm where you could use either key to encrypt. This is known as the RSA algorithm. This made possible the full use of asymmetric encryption for the purposes we have discussed - certificates, non-repudiation, etc, as well as confidentiality - and thus made PKI systems possible.

Parent topic: Asymmetric Algorithms
Parent topic: SSL and PKI Technology Primer
Previous topic: Diffie-Hellman (D-H)
Next topic: Hashing


MD5

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This is probably the most commonly used hash function. It produces a 128-bit hash. It has largely superseded earlier MD functions (for example, MD2, MD4). It is defined in RFC1321.

MD5 has been shown to be vulnerable to collisions in some applications. It can still be used for most purposes in SSL, but SHA is now preferred for new applications.

Parent topic: Hashing
Parent topic: SSL and PKI Technology Primer
Previous topic: Hashing
Next topic: SHA
Related information
RFC1321


SHA

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Secure Hash Algorithm (SHA) is a US standard, developed by the National Institute of Standards and Technology (NIST). SHA-1 is a revised version, published in 1994. It produces a 160-bit hash, which is more secure than MD5's 128-bit hash. It is defined in RFC3174 .

There are several further revisions of SHA, described on the NIST Web site at www.csrc.nist.gov/cryptval/shs.htm.

It is expected that a revision of SHA will replace MD5 as the most popular hashing algorithm.

Parent topic: Hashing
Parent topic: SSL and PKI Technology Primer
Previous topic: MD5
Next topic: Digital Signatures
Related information
RFC3174
www.csrc.nist.gov/cryptval/shs.htm


Digital Signatures

Restriction: This topic applies only when the Enterprise Server feature is enabled.

As explained earlier, a digital signature on a message consists of an encrypted hash of the message - first the message is hashed, and then the hash is encrypted using the private key of the signatory (usually a CA).

The recipient can check the signature by decrypting it using the signatory's public key, then hashing the message him/herself and comparing the two results.

Many methods of hashing are possible, combining different encryption algorithms with different hashing algorithms. One is particularly worth mentioning.

  • Digital Signature Standard (DSS)
Parent topic: Some Common Algorithms: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: SHA
Next topic: Digital Signature Standard (DSS)


Digital Signature Standard (DSS)

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This is a US standard. It specifies that SHA-1 is to be used for the hashing, and a specially designed asymmetric algorithm called Digital Signature Algorithm (DSA) is to be used for the encryption. DSA can only be used for signing, not for other encryption.

Parent topic: Digital Signatures
Parent topic: SSL and PKI Technology Primer
Previous topic: Digital Signatures
Related information
FIPS PUB 186


Definitions for OpenSSL

This topic briefly explains some terms that, while they are not part of SSL, often appear in discussions and documentation of SSL, especially of OpenSSL.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Overview
  • Base64 Encoding
  • SSLeay
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Overview


Overview

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Abstract Syntax Notation number One (ASN.1) is a notation used extensively by standards committees and other bodies for defining protocols for use in data communications. It resembles a programming language, but consists mostly of features for defining data structures. There are various data types, and syntax for building up complex data structures out of these elementary types. You might think of a protocol specification written in ASN.1 as resembling the Data Division of a COBOL program, although the actual syntax of the language is more like C.

You may well never see an example of ASN.1, since it is for use in defining protocols, and even protocols themselves tend to be things that the user does not see directly. Nevertheless, ASN.1 is very widely used, and a great many electronic devices in every day use - from air traffic control systems to washing machines - use data transmission protocols that were designed using ASN.1.

Many of the standards used in SSL that we have been discussing were designed in ASN.1, and consequently you will sometimes come across ASN.1 terminology when reading about SSL. This is especially true of the documentation for OpenSSL. Although as an end-user, or as a COBOL developer, you are unlikely to come directly in contact with these concepts, you will find the OpenSSL documentation easier to follow if we explain some of them.

  • ASN.1 Compiler
  • Encoding Rules
  • Distinguished or Canonical Encoding Rules
  • Object Identifiers
  • Octets
  • UTF8String
  • Further Information
Parent topic: Definitions for OpenSSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Definitions for OpenSSL
Next topic: ASN.1 Compiler


ASN.1 Compiler

Restriction: This topic applies only when the Enterprise Server feature is enabled.

People who are implementing protocols designed in ASN.1 often use an ASN.1 compiler, which translates a protocol specification from ASN.1 into source code in a programming language. For the C programming language, for example, the compiler would probably output a C header file (similar to a COBOL copyfile), for inclusion in a C program.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Overview
Next topic: Encoding Rules


Encoding Rules

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A protocol specification in ASN.1 specifies the data structures in a source-like, human-readable way. It says nothing about how those data structures are to be represented when actually transmitted. The bodies responsible for defining ASN.1 have defined encoding rules, which specify how each data structure that you can specify in ASN.1 is to be represented as a bit pattern.

There are in fact several alternative sets of encoding rules that the committees have designed over the years. The earliest set is called the Basic Encoding Rules (BER), and a later one, which produces much more compact messages, is called the Packed Encoding Rules (PER).

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: ASN.1 Compiler
Next topic: Distinguished or Canonical Encoding Rules


Distinguished or Canonical Encoding Rules

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Clearly a set of encoding rules must be such that any particular bit pattern corresponds to just one ASN.1 data structure - otherwise software receiving a message would not know which data structure to interpret the bit pattern as. However, the reverse is not necessarily the case - no ambiguity is caused if several different bit patterns can represent the same ASN.1 data structure.

Nevertheless, in some applications, if different bit patterns can represent the same ASN.1 data structure, it does cause problems. For these applications, it's desirable to have a set of encoding rules where each ASN.1 data structure converts to just one bit pattern, and vice versa. This is especially true in secure communications, because if you are digitally signing messages you need semantically equivalent messages to always have the same encoding.

Such a set of encoding rules is called canonical, or distinguished. Two such sets of rules have been developed - one was named the Distinguished Encoding Rules (DER) and the other was named the Canonical Encoding Rules (CER). CER has not caught on, and is very seldom used. However, the standard file extension for a file containing DER is .cer.

In reading documentation of OpenSSL, you will often see mentions of data stored in DER format.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Encoding Rules
Next topic: Object Identifiers


Object Identifiers

Restriction: This topic applies only when the Enterprise Server feature is enabled.

An important data type in ASN.1 is the object identifier. An object identifier (OID) is a reference number, unique in the world, that can be allocated to, in principle, any object; in practice, to any object that can be represented as a set of information. The object identifiers form a tree structure, which you can access at Object identifier tree. The branches of the tree are referred to as arcs, and various organizations have been allocated responsibility for assigning nodes in particular parts of the tree to anyone who requests one, to represent particular objects.

Each node has a number, and optionally, a name. An object's OID is the list of numbers representing the nodes in the tree from the root to that object's own node. They are normally shown enclosed in braces and separated by spaces. If a node's name is shown as well, the node's number is normally shown in parentheses. Only the numbers are intended to be machine-readable - the names are there to be human-readable.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Distinguished or Canonical Encoding Rules
Next topic: Octets
Related information
Object identifier tree


Octets

Restriction: This topic applies only when the Enterprise Server feature is enabled.

COBOL programmers are used to working with memory physically organized into groups of eight bits, and calling these groups bytes. However, in communications, where we are talking about a continuous stream of bits on the wire, each group of eight bits is called an octet.

The ASN.1 encoding rules define four types of octet: identifier octet, length octet, contents octet, and end-of-content octet. There's no need to go into detail here about exactly how these are used (it's different for different encoding rules anyway); it suffices to say that the contents octets contain the actual data, while the others are needed for the syntax of the encoded bit-stream.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Object Identifiers
Next topic: UTF8String


UTF8String

Restriction: This topic applies only when the Enterprise Server feature is enabled.

ASN.1 has a number of different string data types. They differ in the range of characters they can support, and in how many octets are used to represent each character.

The string data type you will see mentioned most often is the UTF8String. This is the best data type for internationalization. UTF8 stands for UCS Transformation Format, 8-bit (where UCS stands for Universal Character Set). It in fact uses a variable-length encoding. The original ASCII characters have exactly the same encoding as in ASCII itself, using 7-bits, and with the top bit set to zero. All other characters have the top bit set to 1. Because the encoding is variable length, all known characters can be represented.

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: Octets
Next topic: Further Information


Further Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

For detailed information on ASN.1, see ASN.1 Information Site

The formal standards documents on ASN.1 and its encoding rules are published by the International Telecommunications Union Telecommunications Sector (ITU-T) and International Standards Organization (ISO) / International Electrotechnical Commission (IEC).

Parent topic: Overview
Parent topic: SSL and PKI Technology Primer
Previous topic: UTF8String
Next topic: Base64 Encoding
Related information
ASN.1 Information Site


Base64 Encoding

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The bit patterns produced by the encoding rules described above are unlikely, in general, to correspond to printable characters. But sometimes it's convenient to represent the encoded data in printable form. This can be done by converting it to base64 encoding.

Base64 is a scheme for converting binary data to printable ASCII characters, namely the upper- and lower-case Roman alphabet characters (A–Z, a–z), the numerals (0–9), and the "+" and "/" symbols, with the "=" symbol as a special suffix code.

The data's original length must be a multiple of eight bits. To convert data to base64, the first byte is placed in the most significant eight bits of a 24-bit buffer, the next in the middle eight, and the third in the least significant eight bits. If there are fewer than three bytes to encode, the corresponding buffer bits will be zero. The buffer is then used, six bits at a time, most significant first, as indices into the string "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/" and each character thus selected is output.

This is repeated until the input data is exhausted. If at the end only one or two input bytes remain, then only the first two or three characters of the output are used, and the output is then padded with two or one "=" characters respectively. This prevents anyone adding extra bits to the reconstructed data.

The resulting base64-encoded data is approximately 33% longer than the original data, and typically appears as seemingly random characters.

Base64 encoding is specified in full in RFC 1421 and RFC 2045.

Many of the commands provided by the openssl.exe utility can convert between normal binary encoding and base64 encoding.

Parent topic: Definitions for OpenSSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Further Information
Next topic: SSLeay


SSLeay

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Open SSL documentation occasionally mentions SSLeay, mainly where it needs to discuss compatibility of OpenSSL with SSLeay.

After SSL was first introduced by Netscape, an independent implementation of it was developed, the SSLeay library by Eric A. Young and Tim Hudson. This was released in 1995. OpenSSL is based on this SSLeay library.

Parent topic: Definitions for OpenSSL
Parent topic: SSL and PKI Technology Primer
Previous topic: Base64 Encoding


Attacks

This topic explains some of the best known strategies for breaking a code, and what features SSL has that you can use to protect yourself from these attacks.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Terminology
  • Brute Force Attack
  • Dictionary Attack
  • Replay Attack
  • Man-in-the-Middle Attack
  • Truncation Attack
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: Terminology


Terminology

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A message sent unencrypted is said to be in cleartext or plaintext. A message sent encrypted is said to be in ciphertext.

The US government used to restrict the strength of encryption it allowed to be included in software for export - beyond a certain strength, encryption is regarded as of military value. In January 2000 these restrictions were mostly removed. Nevertheless a lot of encryption software still exists that was designed in that period to be exportable. The term "export cipher" means an algorithm and key length designed to be exportable under these regulations.

The information given here is believed to be correct at the time of writing, but remember that typical computer power and legal requirements are constantly changing.

The word "cipher" is often used to mean an encryption algorithm. A particular algorithm with a particular key length is often referred to by the algorithm's abbreviated name followed by a hyphen and the key length. For example, RC4-40 means "Rivest Cipher 4 with 40-bit keys".

Short keys are usually called small or weak keys.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Attacks
Next topic: Brute Force Attack


Brute Force Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This consists of simply going through every possible key, deciphering the ciphertext with each key, and trying to find some recognizable cleartext in the result. If you use a 128-bit key there are 2128 possible keys.

A would-be code-breaker would regard this type of attack as the last resort, to be used only if there is no feature - that is, weakness - of the cipher that makes possible some more intelligent attack. A cipher that forces the code-breaker to resort to this method is a strong cipher.

However, ciphers that use weak (small) keys are susceptible to brute force attack, in particular RC4-40, RC2-40 and DES-56. There have been many successful brute force attacks against RC4-40 since its release in February 1995.

A brute force attack against ciphers with 128 bits or more is probably impractical in the foreseeable future.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Terminology
Next topic: Dictionary Attack


Dictionary Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This type of attack can be used when the attacker knows or guesses some part of your original message. In the case of a protocol, this may be easy - for example, in HTTP messages the "get" command often appears.

The attacker takes the known cleartext and encrypts it using every possible key. The resulting set of ciphertexts is saved. This set of saved ciphertexts is called a dictionary.

When the attacker gets hold of an encrypted message, he or she searches it for occurrences of any of these ciphertexts. When a match is found, then the key that gave that ciphertext must be the key that was used to encrypt the whole message.

SSL protects you from this kind of attack by using various technical measures that ensure the same plain text produces different ciphertext each time.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Brute Force Attack
Next topic: Replay Attack


Replay Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In a replay attack, an attacker records an exchange of messages between a client and server and tries to recreate the exchange later by resending the client messages to the server.

To prevent this, SSL has a nonce number. This is a connection-id, which the server generates as a random number and sends to the client together with the server certificate. Since the nonce is different for each session, someone resending the old set of client messages cannot fool the server into thinking they are a new set. SSL nonces are 128 bits long.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Dictionary Attack
Next topic: Man-in-the-Middle Attack


Man-in-the-Middle Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In a man-in-the-middle attack, an attacker intercepts messages and modifies them, and then passes them on to the intended recipient.

SSL's system of certificates and private keys prevents this. An attacker would have to fake a certificate and somehow get it signed with a CA's key.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Replay Attack
Next topic: Truncation Attack


Truncation Attack

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In a truncation attack, an attacker inserts into a message a TCP code indicating the message has finished, thus preventing the recipient picking up the rest of the message.

To prevent this, SSL from version v3 onward has a closing handshake, so the recipient knows the message has not ended until this has been performed.

Parent topic: Attacks
Parent topic: SSL and PKI Technology Primer
Previous topic: Man-in-the-Middle Attack


Designing a PKI

This chapter advises on points to remember, ideas to consider, and pitfalls to avoid if you are designing a PKI for your organization. This is by no means an exhaustive list, but is intended to be helpful in suggesting points to consider.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • General Points
  • Client Certificates
  • Security
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: General Points


General Points

Restriction: This topic applies only when the Enterprise Server feature is enabled.
  • Don't design a PKI with a particular application in mind - rather, think of it as a fundamental part of your organization's general data processing setup. If you design it for use with a particular application, you are likely to find it inflexible when you try to use it with other applications.
  • Authentication doesn't imply authorization. Just because someone has the necessary keys to access your data, that doesn't mean they necessarily should be allowed access to all your data. You should still have other mechanisms, for example an access control list (ACL), to ensure people can only access data appropriate to their position.
  • You should make people change their keys from time to time, by applying for new certificate/key pairs. That way if a private key is stolen without anyone noticing, at least it will become useless to the thief next time the certificate/key pair is changed.

    This applies to all private keys - client keys, server keys, subordinate CA keys, and root CA keys.

    The easiest way to enforce this is to include expiry dates in certificates.

  • There are many ways of structuring your tree of trust. Should there be just one root CA, or several? Should subordinate CAs be able to grant CA certificates to other subordinate CAs, or should only root CAs be able to do this?
  • Will your CAs sometimes need to revoke certificates? The commonest way to do this is for a CA to maintain a certificate revocation list (CRL), a list of certificates it has granted and later revoked (they can be deleted from the list once they expire). Users can obtain the CRL and install it in their SSL software.
  • Will users generate their own private keys? In some setups, the CA generates both the certificate and the private key for the user. This saves the ordinary user needing to know how to create a certificate signing request (many of the major CAs on the Web are willing to work in this way) but it means the private key must somehow be conveyed securely to the user. To obtain the maximum security benefit of asymmetric encryption - that the private key is never sent anywhere, so can't be listened in on - the user should him/herself use openssl.exe to create a private key and the matching certificate signing request, and send the latter to the CA, so the CA can create the certificate.
  • It may be an advantage to have all certificate requests handled by your subordinate CA machines. Then your root CA machine only needs to be online when you are using it to certify subordinate CAs. After that it can be taken offline, or at least its private key can be stored offline, until you need it to certify more subordinate CAs. This can greatly improve the security of the root CA, by reducing to a minimum the times when it could be accessed illicitly. It also means the users are not dependent on a single machine, the root CA machine, to keep functioning.

    It will still be possible - and simpler - to have your users install the root CA's certificate in their browsers (or whatever SSL-enabled software they use) rather than the certificates of all the subordinate CAs.

  • If you want really tight control, you might want to delete from your Web browser all the CA certificates that have been installed by default, and install just certificates of your own choosing - from your own CA, if you are setting up a private PKI. However you'd have to think carefully about the effect on accessing other Web sites outside your PKI.
  • If as a Web site owner you want the benefits of non-repudiation, that is, you want to be able to prove that data really was sent to you from a particular client, then you should use full authentication - you can if you wish generate client certificates for your clients (acting as a CA to this extent) and send the clients their certificates for them to store and use. Remember your clients will need to understand how to install these personal certificates in their software, e.g. their browsers.
  • It's worth pointing out a few features of the "world-wide" PKI used on the World Wide Web, which you may or may not choose to emulate in your own PKI:
    • It uses server-only authentication - although there's nothing to stop a particular online service arranging with its known clients that they should have to have certificates.
    • All CAs are equally trusted - there's no concept of some being trusted more than others.
  • When a certificate/keyfile pair is created, you can create pass phrases to protect them. It's essential to protect the keyfile in this way, because a private key is extremely sensitive information and every form of security available should be used to protect it. However, a certificate is intended to be available to anyone who wants to see it, so it's seldom appropriate to protect it in this way.

Parent topic: Designing a PKI
Parent topic: SSL and PKI Technology Primer
Previous topic: Designing a PKI
Next topic: Client Certificates


Client Certificates

Restriction: This topic applies only when the Enterprise Server feature is enabled.

In looking at certificates installed in Web browsers, you may have noticed that (using Internet Explorer terminology, but the situation is the same with any Web browser) the Personal and Other People's lists are empty or nearly empty, while the Intermediate CA and Trusted Root CA lists contain many entries.

This is a fairly typical situation. As an ordinary Web user, you probably don't actually need a certificate of your own - Web businesses such as online banks and shops generally use server-only authentication. As for Other People's, you could install server certificates sent to you by such online businesses, but it's generally unnecessary as these businesses send their certificates in the initial hand-shake of any communication session. It's much more necessary to have CA certificates installed, since these are needed to validate the certificates these businesses send you.

You might sometimes find it useful to install an entity's client certificate, if you communicate with them peer-to-peer rather than client/server.

Parent topic: Designing a PKI
Parent topic: SSL and PKI Technology Primer
Previous topic: General Points
Next topic: Security


Security

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The security of your CA and RA machines is vital.

Remember you need to ensure reliability and availability, as well as confidentiality and trustworthiness.

Remember that SSL protects data only while it is in transit - once it has been received and stored, it is no longer encrypted, and so you need to look to other methods to ensure it remains confidential.

  • Controlling Network Access
  • Controlling Physical Access
  • Backups
Parent topic: Designing a PKI
Parent topic: SSL and PKI Technology Primer
Previous topic: Client Certificates
Next topic: Controlling Network Access


Controlling Network Access

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You will of course need to protect your machines with a firewall and with virus scanning, and require any user accessing the machines remotely (if you allow this at all) to login, giving their user ID and password.

It's advisable to have the latest version of your operating system - the security features are usually improved at each upgrade.

Parent topic: Security
Parent topic: SSL and PKI Technology Primer
Previous topic: Security
Next topic: Controlling Physical Access


Controlling Physical Access

Restriction: This topic applies only when the Enterprise Server feature is enabled.

You should certainly require anyone using your CA and machines locally on to login, giving their user ID and password, and you should probably control access to the computer room too, so that no-one authorized can even get to the machine.

Also ask yourself about other ways an interloper could get in. Could someone insert an USB device between the printer and the system? Could someone run code from an I/O device? Could someone trick their way into your site by talking to the people who work there, finding out how they work, and emulating them?

Parent topic: Security
Parent topic: SSL and PKI Technology Primer
Previous topic: Controlling Network Access
Next topic: Backups


Backups

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The private keys of your CA machines are vital. Keep them backed up to guard against accidental loss - but keep the backups every bit as secure as the system itself, to guard against them being stolen.

Parent topic: Security
Parent topic: SSL and PKI Technology Primer
Previous topic: Controlling Physical Access


Secure Communications (SSL) Legal Information

Restriction: This topic applies only when the Enterprise Server feature is enabled.

OpenSSL Acknowledgment

The SSL support provided by the Micro Focus Security Pack is based on OpenSSL.

The OpenSSL project is a collaborative effort to develop a robust, commercial-grade, full-featured, and Open Source toolkit implementing the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols as well as a full-strength general purpose cryptography library. The project is managed by a worldwide community of volunteers that use the Internet to communicate, plan, and develop the OpenSSL toolkit and its related documentation.

For further information, see the OpenSSL home page at http://www.openssl.org .

Usage and Export

The ability to send messages in an encrypted form is regarded in some parts of the world as being of military value, and therefore is subject in some countries to legal restrictions and export controls.

Important:

Therefore it may be illegal to use or export SSL or PKIs in or to some countries. You must check the legal position in your country.

Restrictions on Algorithms and Key Lengths

Some encryption or hashing algorithms available in OpenSSL are under patent. Micro Focus has, to the best of its knowledge, not included these in the SSL support included with this COBOL system.

The use of some key lengths may be legally restricted in some countries, because longer key lengths give stronger protection, and therefore may be considered of military value.

Important:

We recommend you take the advice of your own legal department, especially regarding conditions in your country, and especially if you will be shipping products of your own incorporating these features.

Parent topic: Securing Communications


Enterprise Server License Messages

Enterprise Server issues messages on your licenses in the console log, which you can view from the Enterprise Server Administration console:

  • CASSI1002S Server manager initialization failure, no valid license found
    There is no Enterprise Server license installed.
  • CASKC1000I ES concurrent request limit: number
    This shows the number of user requests that your enterprise server is permitted to process concurrently.
  • CASKC1001W Warning: Concurrent request limit exceeded number times
    Your Enterprise Server license permits you to process a limited number of user requests concurrently. You have exceeded this limit.
  • CASKC1002I ES concurrent request limit: number, actual: number
    This states that the maximum number of user requests that were processed by the enterprise server concurrently during the session exceeded the maximum allowed. This message is displayed when you stop the enterprise server and also when the maximum number of concurrent user requests is exceeded.
Parent topic: Enterprise Server


CASSI1002S Server manager initialization failure, no valid license found

Resolution:

Install an Enterprise Server license using AppTrack, the License Administration utility.

Parent topic: Enterprise Server License Messages


CASKC1000I ES concurrent request limit: number

Resolution:

This message is for information only.

Parent topic: Enterprise Server License Messages


CASKC1001W Warning: Concurrent request limit exceeded number times

Resolution:

Contact your Micro Focus representative for an additional Enterprise Server license.

Parent topic: Enterprise Server License Messages


CASKC1002I ES concurrent request limit: number, actual: number

Resolution:

The maximum number of concurrent processes allowed is determined by the 'Requested Licenses' value - this can be increased to allow more concurrent processes.

See the section To Change the Number of ES licenses for details on how to do this.

Parent topic: Enterprise Server License Messages


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 2.2 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

Restriction: This command is supported for native COBOL only.

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.

Comments:

UNIX only: use cobrun in conjunction with the effective working mode to run in a 32-bit or 64-bit environment; alternatively, use cobrun32 or cobrun64 to directly invoke those environments.

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.
  • COBRT081 - COBRT100
    Lists the Run-time System error messages from COBRT081 through COBRT100.
  • 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 2.2 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.

Comments:

If the RTS is unable to write an error message to the screen (for example, when running in a Windows service), then the run-time error message will instead be sent to the Windows Application event log.

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 Index structure corrupt (Recoverable)
    The index of your data file has become corrupt, and although it still may be accessible, you should rebuild it.
  • 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 Index structure corrupt (Recoverable)

The index of your data file has become corrupt, and although it still may be accessible, you should rebuild it.

Resolution:

Use the Rebuild utility to rebuild the corrupt index. Use the options /d and /e when rebuilding the file; for example:
rebuild filename1,filename2 /d /e
and then rename filename2 to filename1.
Note: Other rebuild parameters may be required, depending on your data file.
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, redirect your program's file operations to alternative storage.

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 does not already exist. If the directory is full, either delete any files that you no longer need or, if your operating system supports this, redirect your program's file operations to alternative storage. 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


COBRT081 - COBRT100

  • 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)
  • COBRT097 Acu library routine is and will remain unimplemented
    The source code contains an ACUCOBOL-GT library routine that is not (or will ever be) supported in Visual COBOL.
  • COBRT098 The library routine is not available in Visual COBOL (<routine-name>) Please contact Micro Focus Customer Care for information
    The source code contains an ACUCOBOL-GT library routine that is not currently supported in Visual COBOL.
  • 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.
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: COBRT081 - COBRT100


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: COBRT081 - COBRT100


COBRT086 Remote file system failure (Fatal)

Parent topic: COBRT081 - COBRT100


COBRT097 Acu library routine is and will remain unimplemented

The source code contains an ACUCOBOL-GT library routine that is not (or will ever be) supported in Visual COBOL.

Remove the call from your source code to avoid the error.

Refer to ACUCOBOL-GT Library Routines for a list of supported library routines, or browse the Library Routines section of the documentation to see if there is a Micro Focus equivalent routine that you can use instead.

Parent topic: COBRT081 - COBRT100


COBRT098 The library routine is not available in Visual COBOL (<routine-name>) Please contact Micro Focus Customer Care for information

The source code contains an ACUCOBOL-GT library routine that is not currently supported in Visual COBOL.

Remove the call from your source code to avoid the error.

It may be supported in the future, and so you should contact Customer Care to register your need for it, especially if you cannot code around the issue.

Refer to ACUCOBOL-GT Library Routines for a list of supported library routines, or browse the Library Routines section of the documentation to see if there is a Micro Focus equivalent routine that you can use instead.

Parent topic: COBRT081 - COBRT100


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: COBRT081 - COBRT100


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: COBRT081 - COBRT100


COBRT101 - COBRT120

  • 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


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.
Parent topic: COBRT101 - COBRT120


COBRT115 Unexpected signal (Fatal)

A signal the run-time system was not expecting has been caught.
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.

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.
  • 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


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; see the memory_strategy and memory_free_check_size tunables.
    Note: This 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

  • The Consolidated Tracing Facility
    The Consolidated Tracing Facility (CTF) is a tracing infrastructure that enables you to produce diagnostic information of Micro Focus software components and your own programs.
  • Profiler
    Profiler is a facility that enables you to obtain detailed statistics on the run-time performance of a COBOL program.
  • 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 2.2 for UNIX


The Consolidated Tracing Facility

The Consolidated Tracing Facility (CTF) is a tracing infrastructure that enables you to produce diagnostic information 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
  • To enable CTF tracing of a web application
    Configure CTF tracing to pass tracing information on to the Java logging framework on a web server. Use this method if you are unable to configure the TEXTFILE or BINFILE emitters due to web server permission restrictions.
  • 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 ctf.cfg configuration file, before you invoke the application. For example:
    export MFTRACE_CONFIG=/home/usr/ctf/ctf.cfg
  2. 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.
  3. Edit the configuration file to specify the information to trace, for example:
    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
    Note: If the location of the log file is specified in the configuration file, as shown above, it overrides the MFTRACE_LOGS setting.
  4. Run the application from the environment you set up.

If you are using a JVM environment, you can also configure CTF tracing by using an mfjvm.ctf file, ensuring it is stored on the program's classpath. The format of this file is the same as the ctf.cfg file and is typically used when tracing web applications is required.

You can ensure the file is on the classpath by:
  • Specifying the path name to the directory the file is stored in, using the standard JVM CLASSPATH system variable.
  • Placing it in the root of a .jar file that is itself on the classpath.
  • Placing it in the WEB-INF/classes directory of a web services .war file.
Note: If the MFTRACE_CONFIG variable is also set, that is used in preference to this method.
Parent topic: The Consolidated Tracing Facility
Related reference
mftrace.application
mftrace.dest
mftrace.dest.component-name
mftrace.comp.component-name#property
mftrace.time
mftrace.level
mftrace.level.component-name
mftrace.emitter.emitter-name#property


To enable CTF tracing of a web application

Configure CTF tracing to pass tracing information on to the Java logging framework on a web server. Use this method if you are unable to configure the TEXTFILE or BINFILE emitters due to web server permission restrictions.

Your project must be of type Dynamic Web Application.

  1. In COBOL Explorer, right-click the project name, then click New > Folder.

    The New Folder screen appears.

  2. In the Folder name field, type Resources, then click Finish.

    The Resources folder is created in your project hierarchy.

  3. Right-click the Resources folder, then click New > File.

    The New File screen appears.

  4. In the File name field, type mfjvm.cfg, then click Finish.

    The mfjvm.cfg configuration file is added to the Resources folder.

  5. Add the configuration file to the deployment:
    1. Right-click the project name, then click Properties.

      The Properties screen appears.

    2. On the Deployment Assembly tab, click Add > Folder > Resources, then click Finish.
    3. Double-click the Deploy Path entry for the Resources source and update it to WEB/INF/classes, then click OK.

  6. Double-click mfjvm.cfg and add the following:
    mftrace.dest = javalogger
mftrace.emitter.javalogger#Format = ruid=$(RUNUNIT) tid=$(THREAD) $(COMPONENT) $(EVENT) :$(DATA)
  7. Compile and deploy your web application, then configure the Java logging API as per your web server documentation.
Parent topic: The Consolidated Tracing Facility
Related information
JAVALOGGER Emitter Properties


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: The Consolidated Tracing Facility
Related information
Example CTF Configuration Files
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: 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 information
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 information
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 information
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.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: The Consolidated Tracing Facility


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 | 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 reference
mftrace.comp.component-name#property
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.
  • mftrace.time
    Specifies the time standard to use when time stamping CTF trace files.
  • Example CTF Configuration Files
Parent topic: 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
Related information
To enable CTF tracing
Components Traced by 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
mf.rts Properties
To enable CTF tracing
Components Traced by 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
To enable CTF tracing
Components Traced by CTF
Emitter List


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
To enable CTF tracing
Components Traced by CTF
Emitter List


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
To enable CTF tracing
Components Traced by CTF
Emitter List


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
Components Traced by 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
To enable CTF tracing
Components Traced by CTF


mftrace.time

Specifies the time standard to use when time stamping CTF trace files.

Syntax:

mftrace.time=time-type

Parameters:

time-type
One of:
UTC
Coordinated Universal Time (UTC) is used to time stamp the CTF trace files.
local
The local time is used to time stamp the CTF trace files.

Default:

mftrace.time=local.

Comments:

On UNIX platforms, set mftrace.time=UTC if you are expecting signals to occur during the run of your application.

Examples:

To time stamp your CTF trace files with the UTC time:

...
mftrace.time=UTC
...

To time stamp your CTF trace files with the local time:

...
mftrace.time=local
...
Parent topic: Configuration File for CTF
Related information
To enable CTF tracing
Components Traced by CTF


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.
  • JAVALOGGER Emitter Properties
    Set the JAVALOGGER emitter properties to control the details passed to the Java logging framework on a web server.
  • TEXTFILE Emitter Properties
    Set the TEXTFILE emitter properties to control the behavior and appearance of the text trace file.
Parent topic: 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.
$(PLATFORM)
A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files. Can be one of:
native
For all native processes
dotnet
For Microsoft .NET processes
jvm
For JVM processes
$(RUNUNIT)
A unique number that represents the managed RunUnit ID (applies to .NET and JVM COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the managed RunUnit (applies to .NET and JVM COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the managed RunUnit (applies to .NET and JVM COBOL only).
$(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
FORMAT
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
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.

if $(RUNUNIT), $(RUNUNIT_SESSIONNAME), or $(RUNUNIT_GUID)" is used, the file name will be unique, therfore MultiProc is not required (applies to .NET and JVM COBOL only)

FALSE, indicating that the configured trace file includes only events from the current process
Rununitid | Controls whether the RunUnit information is included in the trace. | TRUE

Performance considerations:

When using the MultiProc property, and two or more COBOL run-time systems (native, .NET or JVM) are executing in the same process, sharing the same trace file is not a performant configuration. Using the $(PLATFORM) variable in the filename allows you to use different filenames for different run-time systems. If tracing includes the $(PID) variable, you can safely set the MultiProc property to false. For example:

$(APPNAME). $(EMITTER).$(PID).$(PLATFORM).ctb

When a JVM or .NET COBOL application executes in a multi-user environment, the user of managed RunUnits should be used. The default filename for both the TEXTFILE and BINFILE emitter collects all the trace events into one or more files. However, if the configuration property #file uses $(RUNUNIT), $(RUNUNIT_SESSIONNAME) or $(RUNUNIT_GUID), separate files can be created for each RunUnit. For example:

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_GUID).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_SESSIONNAME).log

JVM COBOL restrictions:

If a JVM COBOL application is executing in a permissions-restricted environment, use of the MultiProc property on the BINFILE emitter is not available.

Parent topic: Emitter List
Related information
Example CTF Configuration Files
CTF Trace File Formats


JAVALOGGER Emitter Properties

Set the JAVALOGGER emitter properties to control the details passed to the Java logging framework on a web server.

Use this type of emitter if you are unable to configure the TEXTFILE or BINFILE emitters due to web server permission restrictions.

Add the required properties for the JAVALOGGER emitter to the mfjvm.ctf configuration file:

Property Description Default
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: warn
  • 3: error
  • 4: fatal
Note: See Comments below.
$(PID)
The current process identifier. Same as $(PROCESS).
$(PROCESS)
The current process identifier. Same as $(PID).
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(TIME) $(COMPONENT) $(EVENT) $(LEVEL) $(DATA)

Comments:

The tracing levels set by $(LEVEL) map to the following levels used in the Java logging API:

Micro Focus tracing levels | Java logging API tracing levels
Debug | Config
Info | Info
Warn | Warning
Error | Severe
Fatal | Severe

Refer to your Java logging API documentation for the details traced for each level.

Parent topic: Emitter List
Related tasks
To enable CTF tracing of a web application


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:

Property | Description | Default
DELIMCHAR | The character used in the output file to delimit trace data parts for a trace event. | 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, if run.exeis invoked, $(APPNAME) has the value "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.
$(PLATFORM)
A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files. Can be one of:
native
For all native processes
dotnet
For Microsoft .NET processes
jvm
For JVM processes
$(RUNUNIT)
A unique number that represents the managed RunUnit ID (applies to .NET and JVM COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the managed RunUnit (applies to .NET and JVM COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the managed RunUnit (applies to .NET and JVM COBOL only).
$(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. | 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).
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(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
 8
LOCATION The folder where the trace files are to be written.

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 multiple processes. If enabled for multiple processes, the File property must also be specified without the $(PID) pseudo-variable embedded in its name.

if $(RUNUNIT), $(RUNUNIT_SESSIONNAME), or $(RUNUNIT_GUID)" is used, the file name will be unique, therfore MultiProc is not required (applies to .NET and JVM COBOL only)

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. . | TRUE

Performance considerations:

When using the MultiProc property, and two or more COBOL run-time systems (native, .NET or JVM) are executing in the same process, sharing the same trace file is not a performant configuration. Using the $(PLATFORM) variable in the filename allows you to use different filenames for different run-time systems. If tracing includes the $(PID) variable, you can safely set the MultiProc property to false. For example:

$(APPNAME). $(EMITTER).$(PID).$(PLATFORM).log

When a JVM or .NET COBOL application executes in a multi-user environment, the user of managed RunUnits should be used. The default filename for both the TEXTFILE and BINFILE emitter collects all the trace events into one or more files. However, if the configuration property #file uses $(RUNUNIT), $(RUNUNIT_SESSIONNAME) or $(RUNUNIT_GUID), separate files can be created for each RunUnit. For example:

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_GUID).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_SESSIONNAME).log

JVM COBOL restrictions:

If a JVM COBOL application is executing in a permissions-restricted environment, use of the MultiProc property on the TEXTFILE emitter is not available.

Parent topic: Emitter List
Related information
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: The Consolidated Tracing Facility
Related information
To enable CTF tracing


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

The 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.

  • CCITCP Configuration
    CCITCP allows an application to connect to another application (on another machine, usually, although it can be another process on the same machine) using the TCP/IP protocol. CCITCP is supported on Windows 95 and later, 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 and record them in a log file. In addition to the this information, you can record data flow information in a separate log file.
  • CCI.INI - The CCI Configuration File
    The CCI.INI file is used to specify selective configuration options for all or some CCI modules installed.
  • CCI Status Messages
    All CCI modules produce text-based messages, describing the status of the completion of the last CCI operation. Some statuses 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.
Parent topic: Micro Focus COBOL Server 2.2 for UNIX


CCITCP Configuration

  • CCI Support For TCP/IP
  • Advanced Features
  • Application Configuration
Parent topic: Configuring CCI
Related information
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 $COBDIR/bin/services file as follows:-

mfcobol 86/udp

Without this entry in the $COBDIR/bin/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 Machine Name
CCITCP Server 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
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

CCI Trace enables you to trace any CCI function calls made by applications and record them in a log file. In addition to the this information, you can record data flow information in a separate log file.

By default, the log file for the trace information, located in the current directory, is called ccitrc1.trc and has a matching index file ccitrc1.idx. Use the trace options to configure your own filename and location.

The log file for data flow information is called ccitrc1d.trc with matching index file ccitrc1d.idx by default.

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.

  • Activating CCI Trace
  • CCI Trace Options
Parent topic: Configuring CCI
Related information
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
  • General Configuration Options for CCI.INI
Parent topic: Configuring CCI
Related information
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 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:-

[cci]
 cci_param_check=yes
 errlog_path=c:\ccilogdir\
 ccitimeout=120000

[ccismem-base]
 mem_file_size=8192
 max_clients=2048
 mem_files_location=c:\ccismem
 log_max_sent_trans=yes
 use_global_namespace=yes
 peer_poll_sleep=300
 errlog_path=c:\ccismemlogdir
 cci_param_check=no

[ccitcp-servers]
  myserver=MFPORT:3000
Parent topic: CCI.INI - The CCI Configuration File


General Configuration Options for CCI.INI

Use the following options in your CCI.INI file:

  • errlog_path
    Enables you to specify a location and filename for the CCI first failure error log file, and filter the types of information written to it.
Parent topic: CCI.INI - The CCI Configuration File
Related concepts
Where to Locate CCI.INI


errlog_path

By default, the CCI first failure log file is called ccierr.log and located in the working directory of the application calling CCI.

To change the name and location, specify the errlog_path option in a protocol-specific section of the configuration file (e.g. [ccitcp]) or in the general section (i.e. [cci]).

There are also other ways to set the location and filename of the log file. A valid setting is searched for in the following order, and when one is found, subsequent settings are ignored:
  1. CCIERRLOG environment variable.
  2. errlog_path setting in a protocol-specific section of CCI.INI.
  3. errlog_path setting in the general section of CCI.INI.
  4. CCI-Option library routine.

Parameters:

The errlog_path setting takes the following parameters:
on/yes
Sets the level of detail recorded to FULL (see filter-type), and uses the default location and log file.
off/no
Turns off tracing.
file-string
Sets the output location and filename of the log file. If the location is omitted, the application's working folder is used. If the filename is omitted, the default name of ccierr.log is used.
Note: If the specified location does not already exist, the log file is not created.
filter-type
Sets the level of detail recorded in the log file. One of:
  • FULL or BASEIO - all options; this is the same as on or yes.
  • INIT - record only session establishment details.
  • TERM - record only session termination details.
  • INIT_TERM - record session creation and termination details.
  • ALL_DATA - record all session data transmissions.
  • SENT_DATA - record session transmission of data.
  • RECEIVED_DATA - record session receipt of data.

Examples:

The following example records errors to the default file ccierr.log in the location usr/ccilogs/.

errlog_path=yes,usr/ccilogs/
Note: If you are only specifying a location, ensure the pathname ends with /.
The following example records all listening and client endpoint startup details, plus any failure messages, to the default location and filename.
errlog_path=INIT

The following example records the same level of detail as the previous example to the location and filename specified.

errlog_path=INIT,usr/ccilogs/initoutput.log
Parent topic: General Configuration Options for CCI.INI
Related concepts
CCI Environment Variables


CCI Status Messages

All CCI modules produce text-based messages, describing the status of the completion of the last CCI operation. Some statuses 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.
  • CCI Status Messages
  • CCI Message Table
Parent topic: Configuring CCI
Related information
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:-

"CCITCP-0001I A CCITCP call has timed-out."

This is broken down in to the following sections:

  • Protocol issuing the message - "CCITCP"
  • Message number - "0001"
  • Severity level - "I"
  • Message text.- "A CCITCP 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.
  • Sort Utilities
    Visual COBOL provides MFSORT, a command line sort and merge utility.
  • 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 2.2 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:

EXTFH=/mydir/test.cfg
export EXTFH
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
Related reference
Configuration File Options


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
Related reference
Configuration File Options


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
Related reference
Configuration File Options


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
Related reference
Configuration File Options


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
Configuration File Options


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
Configuration File Options


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.
  • EXTENDEDESDS
    The EXTENDEDESDS option enables you to create extended ESDS files.
  • EXTENDEDXRBA
    The EXTENDEDXRBA option enables you to use extended relative byte addressing with extended ESDS files.
  • 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.
  • 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
Extended ESDS
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


EXTENDEDESDS

The EXTENDEDESDS option enables you to create extended ESDS files.

Syntax:

EXTENDEDESDS = { ON } { OFF }

Parameters:

ON
When set, new ESDS files are created as extended ESDS files. An extended ESDS file is not limited to 4GB, and therefore you can use extended relative byte addressing with it.
OFF
When set, new ESDS files are created as standard ESDS files.

Properties:

Default: ON

Comments:

This option is synonymous with option IDXFORMAT"16".

Parent topic: Configuration File Options
Related reference
EXTENDEDXRBA


EXTENDEDXRBA

The EXTENDEDXRBA option enables you to use extended relative byte addressing with extended ESDS files.

Syntax:

EXTENDEDXRBA = { ON } { OFF }

Parameters:

ON
Extended relative byte addressing is supported.
OFF
Extended relative byte addressing is not supported.

Properties:

Default: ON

Comments:

Extended relative byte addressing is not available for standard ESDS files (i.e. files limited to 4GB). You must create an extended ESDS file, using EXTENDEDESDS=ON or IDXFORMAT"16", before the EXTENDEDXRBA setting takes effect.

Parent topic: Configuration File Options
Related reference
EXTENDEDESDS


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
Extended ESDS
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: 32
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 in the specified folder (and sub-folders) use Vision, the ACUCOBOL-GT file handler.
RM
All file organizations in the specified folder (and sub-folders) 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:

Take care when applying this option to a folder, as the specified file handler attempts to open any file organizations found on the folder's (and sub-folders') path. Files that are not compatible will produce unwanted behavior. Ensure that only valid files are found on the specified path.

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

Comments:

If you are accessing a file through Fileshare, this option is only applicable to client-side configurations. Setting this option in your server configuration file will have no effect.

Parent topic: Configuration File Options
Related reference
RETRYOPEN
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

Comments:

If you are accessing a file through Fileshare, this option is only applicable to client-side configurations. Setting this option in your server configuration file will have no effect.

Parent topic: Configuration File Options
Related reference
RETRYLOCK
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

Comments:

If you are accessing a file through Fileshare, this option is only applicable to client-side configurations. Setting this option in your server configuration file will have no effect.

Parent topic: Configuration File Options
Related reference
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


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, the 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 corresponds to a 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
Related reference
Run-time System Error Messages


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


Sort 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.
Parent topic: Sort 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. Characters that exceed this limit are processed separately if they form a valid command; however, this may result in undesired sort results. If this truncation causes an invalid or incomplete command, an error is produced.

  • Instructions
Parent topic: Sort 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

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.

Parent topic: Sort Utilities
Related information
Introduction
Invoking Mfsort
Example Commands
Error Messages
MFJSTATS


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: Sort 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 reference
Input Data
Related information
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 reference
Input Data
Related information
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: Sort Utilities
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands
Mfsort Error Messages


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:

  • 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.
  • SORTTYPE
    Determines the method for reading and writing files during SORT operations.
  • TEMPDIR/ TMP/ TEMP
    Determines where the run-time system of the directory stores paging files.
Parent topic: Sorting Files


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
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME


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
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTCOMPRESS


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
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSCHEME
SORTCOMPRESS


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
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


SORTTYPE

Determines the method for reading and writing files during SORT operations.

Parameters

0 or 1
SORT operations use CBL_ routines, where possible, which improves performance.
2
SORT operations use the file handler, so that format modifications are picked up from the extfh.cfg file.

The default value is 0.

Example

SORTTYPE=2
Parent topic: SORT Environment Variables
Related concepts
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


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
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


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:

  • 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.
  • 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


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
Related reference
File Status Codes


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


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 2.2 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 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 Server contains detailed comments that explain the various cci.ini options that you can use to alter the basic 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 ccism
/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 ccism

Specifies that the default communications protocol is CCISMEM. 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 ccism

This entry in the Fileshare Server configuration file enables the Fileshare Server to communicate with Fileshare Clients using the Named Shared Memory (CCISMEM) 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: ccitcp ccism 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 ccitcp
/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 ccitcp

Specifies that ccitcp 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
  • 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 reference
Fileshare Manager
Related information
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
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 reference
Fileshare Manager
Related information
Single User Mode
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
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 reference
Fileshare Manager
Related information
Single User Mode
Filename Mapping
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
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 reference
Fileshare Manager
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Monitoring Fileshare
Fileshare Manager Configuration
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 reference
Fileshare Manager
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Fileshare Manager Configuration
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
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 reference
Fileshare Manager
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Byte-stream I/O Calls
Fileshare Server Configuration
Performance Considerations
Large File Support with Fileshare
Client Configuration


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 reference
Fileshare Manager
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
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 reference
Fileshare Manager
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
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 reference
Fileshare Manager
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
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 reference
Fileshare Manager
Related information
Single User Mode
Filename Mapping
Data and Key Compression
Virtual File Handler Interface
Monitoring Fileshare
Fileshare Manager Configuration
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 2.2 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 2.2 for UNIX


Managing Licenses

  • Overview
  • To start Micro Focus License Administration
  • Installing licenses
  • Viewing installed licenses
  • Uninstalling licenses
  • Trial licenses
  • Commuter licenses
  • Usage log
  • Licensing Error Messages
    Messages you might encounter when working with licensing.
Parent topic: Micro Focus COBOL Server 2.2 for UNIX


Overview

You manage your product licensing by using the Micro Focus License 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 administers licenses, you can request licenses from a central license server.

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 Administration tool that is supplied with your product. Individual workstations can then be configured to obtain a license from the license server machine.

Uninstalling a product that uses Sentinel RMS

Uninstalling a Micro Focus product that uses Sentinel RMS does not remove the license(s) that you have activated for that product, nor does it uninstall the license server. We recommend that before you uninstall the Micro Focus product, you uninstall the licenses for it.

Parent topic: Managing Licenses


To start Micro Focus License Administration

Log on as root, and from a command prompt type:
/var/microfocuslicensing/bin/cesadmintool.sh
Parent topic: Managing Licenses


Installing licenses

  • If you have a license file
  • If you have an authorization code
  • Configuring your machine to use a network license server
Parent topic: Managing Licenses


If you have a license file

  1. Start the Micro Focus License Administration tool and select the Manual License Installation option by entering 4.
  2. Enter the name and location of the license file.
Parent topic: Installing licenses


If you have an authorization code

  • Authorizing your product when you have an Internet connection
  • Authorizing your product when you don't have an Internet connection
Parent topic: Installing licenses


Authorizing your product when you have an Internet connection

Note: This topic only applies if you have an authorization code.

The following procedure describes how to authorize your product using a local or network license server. The license server is set up automatically when you first install the product.

  1. Start Micro Focus License Administration.
  2. Select the Online Authorization option by entering 1 and pressing Enter.
  3. Enter your authorization code at the Authorization Code prompt and then press Enter
Parent topic: If you have an authorization code


Authorizing your product when you don't have an Internet connection

Note: This topic only applies if you have an authorization code.

This method of authorization is required if your machine does not have an Internet connection or if normal (automatic) authorization fails.

In order to authorize your product you must have the following:
  • Your authorization code (a 16-character alphanumeric string).
  • The machine ID. To get this, start the Micro Focus License Administration tool and select the Get Machine Id option by inputting 6. 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 License Administration tool and select the Manual License Installation option by inputting 4.
  7. Enter the name and location of the license file.
Parent topic: If you have an authorization code


Configuring your machine to use a network license server

This topic describes how to configure your machine to use a network license server. You might have already done this when you installed your product.

You need the IP address or server name for the network license server you want to use.
Important: We recommend that Advanced Configuration options other than those referenced here are modified only under guidance from Micro Focus SupportLine.
  1. Start Micro Focus License Administration
  2. Select the Advanced Configuration Options option by inputting 3.
  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: Installing licenses


Viewing installed licenses

  1. Start Micro Focus License Administration
  2. Select the Check License Status option by entering 2.
  3. You can see more information for some licenses, such as type and number of licenses, the date a license was generated and the platform it is for. To do this, return to the License Administration main menu and selecting the Get License Details option by entering 2. This lists the license information - choose the requisite license by entering the corresponding number.

Your entitlement for using this product is governed by the Micro Focus End User License Agreement and by your product order.

Parent topic: Managing Licenses


Uninstalling licenses

Licenses installed with an authorization code have a Revoke link in the Uninstall column. Licenses installed using a license file have a Remove link in the Uninstall column

  • Removing licenses
  • Revoking licenses when you have an Internet connection
  • Revoking licenses when you do not have an Internet connection
Parent topic: Managing Licenses


Removing licenses

Note: This topic only applies if you installed the product using a license file (.mflic).
  1. Start Micro Focus License Administration
  2. Select the Uninstall Licenses option by inputting 5.
  3. Select the license to remove and press Enter.
Parent topic: Uninstalling licenses


Revoking licenses when you have an Internet connection

Note: This topic only applies for licenses installed with an authorization code.

You must revoke licenses if, for example, you want to move your product to a different machine or if you no longer use your product and want to reallocate the license.

You must have write access on the license file that contains the authorization codes.

  1. Start Micro Focus License Administration
  2. Select the Uninstall Licenses option by inputting 5.
  3. Select the license to revoke and press Enter.
  4. Type the number of licenses to revoke and press Enter.
Important: If there is a problem accessing the Micro Focus License Authorization Server and the revocation fails, your licenses are revoked and cannot be used.

An error message is returned confirming there is no Internet connection. This message includes the name of the file containing the License Revocation Tickets (LRTs).

Copy this file into an email and send it to your SupportLine representative.
Parent topic: Uninstalling licenses


Revoking licenses when you do not have an Internet connection

Note: This topic only applies for licenses installed with an authorization code.

You must have write access on the license file that contains the authorization codes.

  1. Start Micro Focus License Administration
  2. Select the Uninstall Licenses option by inputting 5.
  3. Select the license to revoke and press Enter.
  4. Type the number of licenses to revoke and press Enter.

    An error message is returned confirming there is no Internet connection. This message includes the name of the file containing the License Revocation Tickets (LRTs).

  5. Copy this file into an email and send it to your SupportLine representative.
Parent topic: Uninstalling licenses


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.

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.

Parent topic: Managing Licenses


Commuter licenses

A commuter license can be moved temporarily from a license server on your network to your own computer. You can then use that license while you are disconnected from the server. Commuter licenses are useful when, for example, working from home or visiting a client site.

You obtain and manage commuter licenses by using the Micro Focus License Administration tool. If there are any commutable licenses on your network server, you can view a list of them by selecting the Commuter/Return Licenses option.

At the end of your commute period the license on your computer expires. The license is available from your network server when you reconnect. Typically, the maximum commute period is 30 days.

You can return a commute license back to the license server before it has expired. Use the Micro Focus License Administration tool to do this.

Not all licenses are commutable. You must have commuter licenses on your license server.

  • To obtain a commuter license
  • To return a commuter license
Parent topic: Managing Licenses


To obtain a commuter license

  1. Start Micro Focus License Administration
  2. Select the Commute/Return Licenses option by inputting 7.
  3. Select the product whose license you want to commute and press Enter.
Parent topic: Commuter licenses


To return a commuter license

  1. Start Micro Focus License Administration
  2. Select the Commute/Return Licenses option by inputting 7.
  3. Select the product whose license you want to return and press Enter.
Parent topic: Commuter licenses


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 10 MB 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, we recommend that you manage these files accordingly.

Parent topic: Managing Licenses


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: Managing Licenses


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 2.2 for UNIX


Copyright and Trademarks

Copyright © Micro Focus 1984-2013. 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 other than as expressly provided in a written instrument signed by Micro Focus and the user. 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.

2013-12-11

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 2.2 for UNIX


Enterprise Server Execution Control Under Windows

Restriction: This topic applies only when the Enterprise Server feature is enabled.

This topic describes the execution control of COBOL programs running as services and executables.

When a COBOL program runs as a Micro Focus service in an enterprise server instance, it inherits its security credentials from the server manager process that started the SEP.

Usually, Enterprise Server is started using the Micro Focus Enterprise Server Administration user interface, the Web interface to the MF Directory Server. In this event, Enterprise Server Administration (ES Admin) runs as a Windows system service. It is listed as Micro Focus Directory Server in the Services Control Panel. Windows system services run under the user account specified in their Startup options. You can view and change the Startup options using the Services Control Panel.

If Enterprise Server is started using the casstart program, run from the command line by an interactive user, then COBOL service programs use that user's security credentials.

When Enterprise Server is installed, the MF Directory Server is installed as a system service using the Local System user account, with the Allow service to interact with the desktop option selected. With this option selected:

  • The Directory Server is started when Windows boots up. You do not need to log into the system to start the Directory Server. Note that any system service can be set to start up when Windows boots, regardless of the user account it runs under.
  • Using this option allows the console daemon window to display when an enterprise server instance is running. User accounts other than the Local System user account cannot use the Allow service to interact with the desktop option.
  • If the Allow service to interact with the desktop option is not selected, the console daemon window is not displayed. You can however still view the console daemon messages through the ES Admin user interface.

The Local System account does not have privileges for network file access. That means that COBOL service programs that are running in an enterprise server instance that was started through MFDS, using the default configuration, are unable to open network files. To enable network file access from your COBOL service programs, use one of these methods:

  • Log in to Windows using an account with the network file access permissions that you want, and from the command line, start the enterprise server instance using the casstart command.

    COBOL service programs use the logged-in user's network credentials and can access the files that the logged-in user has authorization for.

    The disadvantage of this method is that it must be done manually, that is, the enterprise server instance must be stopped manually (using the casstop command) rather than through ES Admin.

  • Disable MFDS in the Services Control Panel and then start it from the command line using the mfds command while logged in as a user who has the appropriate network file access. When the enterprise server instance is started from ES Admin, it will inherit MFDS's user credentials.

    The disadvantages of this method are similar to the method above, though ES Admin can be used to start and stop enterprise server instances in this case.

  • Change the user account for the MFDS service. If you have the MFDS service running under a user account that has the appropriate network file access, your COBOL service programs will be able to open those files. Note that your programs will need to use UNC paths (that is, file path name of the form \\server\share\path-to-file\filename) and not drive mappings, to reliably open network files.

    The main disadvantage of this method is that Enterprise Server cannot display the console daemon window. However, this does improve the security of the installation, since access to the local desktop is a security risk. Running COBOL application programs under a normal user account (if it has reduced privileges), rather than under the Local System account (which is equivalent to an Administrator account for local security purposes) is more secure.

We recommend that for Enterprise Server on Windows (whether or not your COBOL service programs need network file access), you create a user account specifically for MFDS and the COBOL service programs running under it. Set the permissions on this account appropriately, that is, don't grant it any permissions that the COBOL programs don't need. For additional security, you can set ACLs to grant or deny access to particular objects (directories, files, registry keys) for this user to further control what COBOL service programs can do.

Related information
Defining Enterprise Server Instance Administrators


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.
Related information
Deployment Licensing


To Configure a Security Manager's Environment

Restriction: This topic applies only when the Enterprise Server feature is enabled.

Use this task to configure the environment for a security manager.

Note: When you set this configuration, you can no longer use the Enterprise Server user administration functionality to manage users. You must do this through your normal Microsoft user management interface.
  1. On the Enterprise Server Administration screen, in the left pane, select Security.
  2. Select the Security Managers tab, and in the list of configured security managers, select the one to configure, and click Edit.

    The Configure Security Options screen is displayed.

  3. In the configuration area at the bottom of the screen, add or edit the [LDAP] configuration to add settings you want follows: For example:
    Note: In the example below, the line: user class="user" sets that Enterprise Server uses Microsoft user configurations, and you cannot change these through the Enterprise Server security user interface. Omit this line to configure the default behaviour, which is that you can configure user information stored in an LDAP.
    [LDAP]
base="DC=somecorp,DC=com"
user class="user"
user container="CN=users"
group container="CN=Enterprise Server Groups,CN=MF"
resource container="CN=Enterprise Server Resources,CN=MF"
Related concepts
Configuring Microsoft Users
Related tasks
To Add or Remove a Security Manager in the Pool
Related information
To Edit a Security Manager's Properties
To configure the security facility to use the MLDAP ESM


COBOL Server Installation Options

To install COBOL Server you run setup_cobol_server_2.2_platform which contains a number of product .msi files (Windows Installer packages). When run, setup_cobol_server_2.2_platform performs some initial system checks then sequentially installs the .msi files.

Note: The name of the installable executable in this document is always the name of the executable for COBOL Server - this is cs2010_22.exe for COBOL Server and cs2012_22.exe for COBOL Server 2012.

setup_cobol_server_2.2_platform can take a number of parameters, enabling you to specify a number of different types of installation:

  • Standard Installation
    • Format:
    • setup_cobol_server_2.2_platform
    • Summary:
    • Full installation including License Manager and COBOL Server. During installation you can specify options including the location to which the components are installed.
  • Non-interactive Installation
    • Format:
    • setup_cobol_server_2.2_platform /passive
    • Summary:
    • Full installation, but the components are installed non-interactively using default options and directories.
  • Silent Installation
    • Format:
    • setup_cobol_server_2.2_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_cobol_server_2.2_platform /q InstallFolder=d:\cobolrts
    • Summary:
    • Full installation, but the components are installed non-interactively with no user interface, and COBOL Server is installed to d:\cobolrts.

To see what parameters you can use, execute the following from the command line: setup_cobol_server_2.2_platform /?.

Note:
  • Log files that are created during installation are saved in the folder specified by the TEMP environment variable. To change the location or name of the files, use the /log parameter on your setup command line and specify the path and file name, for example: filename /log d:\temp\log.txt. This creates a log file, named log.txt, in the d:\temp directory.
Related information
Shipping Selected Files from COBOL Server


Configuring Microsoft Users

Restriction: This topic applies only when the Enterprise Server feature is enabled.

With LDAP-based security for Enterprise Server using a security configuration that includes the MLDAP ESM Module, you can configure your installation so that authentication uses the standard Microsoft user objects in Active Directory, that is, the same user objects that are used for Windows authentication. With this configuration, users sign on to Enterprise Server using their Windows usernames and passwords, and Windows logon restrictions apply.

Note: When you set this configuration, you can no longer use the Enterprise Server user administration functionality to manage users. You must do this through your normal Microsoft user management interface.

To configure the system to use Microsoft standard users, you need to set the security manager's configuration as per the example below:

    [LDAP]
    base=
    user class=user
    user container=cn=users,dc=company,dc=com
    group container=cn=enterprise server user groups,cn=micro focus,
      cn=program data,dc=company,dc=com
    resource container=cn=enterprise server resources,cn=micro focus,
     cn=program data,dc=company,dc=com
    [Verify]
    mode=bind

user class environment variable to a value of: user

If this setting is not present, user class=microfocus-MFDS-User which is the default setting is used.

Related tasks
To Configure a Security Manager's Environment
Related information
To configure the security facility to use the MLDAP ESM


To run a native COBOL application from a network server

You need to configure the licensing for COBOL Server when running native COBOL applications from a network server.

Server Side

  1. Install COBOL Server on the server.
  2. Install the license.
  3. Copy mfcesd.exe (the Micro Focus CES daemon) and mfcesdchk.exe (which checks if the Micro Focus CES daemon is running) as follows:
    • On 32-bit Windows - from C:\Program Files\Common Files\SafeNet Sentinel\Sentinel RMS License Manager\WinNT to C:\Program Files\Micro Focus\COBOL Server\bin.
    • On 64-bit Windows - from C:\Program Files (x86)\Common Files\SafeNet Sentinel\Sentinel RMS License Manager\WinNT to C:\Program Files (x86)\Micro Focus\COBOL Server\bin.
  4. Copy msvcr100.dll and msvcr100d.dll from the C:\Windows\System32 folder into the bin subfolder in the COBOL Server installation folder.
  5. Click Start > All Programs > Micro Focus License Manager > License Management System.
  6. Click Options > Advanced Configuration.
  7. Click Change on the row for License server field, specify the IP address or the name of the server, and click Save.
  8. Close the Advanced Configuration and then the Micro Focus Licensing System Administration dialog box.
  9. ces.ini must be on a shared network location and, as you are going to share the bin subfolder in the installation directory of COBOL Server, we recommend you copy the file there - copy ces.ini from C:\ProgramData\MicroFocus into the bin subfolder in the COBOL Server installation directory.
  10. From the bin subfolder in the installation directory of COBOL Server, create a network share with read permission for everyone.
  11. If running 64-bit applications, also create a network share with read permission for everyone from the bin64 subfolder in the installation directory of COBOL Server.
  12. Create a batch file on the server, runit.bat, with the following code:
    @echo off
cls
set MFCES_INIT_LOCATION=\\ServerName\Shared_bin\ces.ini
set PATH=\\ServerName\Shared_bin;%PATH%
rem set PATH=\\ServerName\Shared_bin64;%PATH%
set PATH=Location_of_Apps;%PATH%
mfcesdchk.exe >nul
if errorlevel 1 goto startlic
goto startapp
:startlic
start /B mfcesd -b
:checkloop
mfcesdchk.exe >nul
if errorlevel 1 goto checkloop
:startapp
YourApp

    Where:

    • \\ServerName is the name of the shared server.
    • \\ServerName\Shared_bin with the path to the network share created earlier.
    • MFCES_INIT_LOCATION is the full path to the ces.ini file stored in a shared folder on the server.
    • Location_of_Apps is the location of the your application on the server.
    • YourApp is the command to run your application.
    Note: If you are running 64-bit applications, delete rem in front of the set PATH=\\ServerName\Shared_bin64 statement and replace this with the path to the network share created for 64-bit applications.

Client Side

Before running an application on the server, ensure that the Micro Focus CES daemon, mfcesd.exe, is running because it interacts with the Micro Focus License Manager to check the licensing.

To start the CES daemon:

  1. Set the PATH environment variable to point to the location of the batch file on the shared server you created earlier: \\ServerName\<location of the batch file>
  2. Execute the batch file, runit.bat.


To configure the security facility to use the MLDAP ESM

Restriction: This topic applies only when the Enterprise Server feature is enabled.

The Enterprise Server External Security Facility connects to external LDAP servers through the MLDAP ESM module. To configure this:

  1. Add a security manager to the security manager pool as described by To add a security manager to the pool and specify the following details:
    • Name - This is the name (for example, you might call it MLDAP) that you will use to refer to the security manager when adding it to particular security manager lists.
    • Module - Enter mldap_esm.
    • Connection Path - Enter the address for your LDAP server (e.g. localhost:389).
    • Authorized ID and Password - These refer to the credentials that the MLDAP ESM module will use to connect to and, if you are using the MF Directory Server screens for managing users and resources, write any necessary information to the LDAP server.

    Make sure that the Enabled option is checked. If it is not, the security manager will not be used by any security manager list to which it is added.

  2. Add the security manager to the security manager list for the relevant servers. See To add a security manager to an enterprise server's security manager list, To add a security manager to the Directory server's security manager list and To add a Security Manager to the Default ES Security Manager List.
Related concepts
Configuring Microsoft Users
Related tasks
To Configure a Security Manager's Environment


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 > 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 information
CTF Trace File Formats
Example CTF Configuration Files